Intro
Endpoint: https://api.omnisend.com/api/forms
The Forms Reports API lets you retrieve performance statistics for your forms, list contacts collected through a form, and access A/B test reports for form experiments.
All endpoints are keyed by formID, a 24-character hexadecimal identifier, and require the forms.read scope.
Form summary report
Use GET /api/forms/{formID}/report to retrieve total statistics and a breakdown by device for a form within a date range.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| from | string | Start of the date range (RFC3339, e.g. 2024-01-01T00:00:00Z) |
| to | string | End of the date range (RFC3339, e.g. 2024-01-31T23:59:59Z) |
Metrics
| Metric | Description |
|---|---|
| views | Number of times the form was displayed |
| interactions | Number of user interactions with the form |
| submits | Number of form submissions |
| signups | Number of signups resulting from the form |
The statisticsByDevice object contains the same metrics grouped by device type (for example, desktop, mobile, tablet).
Example: Get form summary report
curl --request GET \
--url 'https://api.omnisend.com/api/forms/000000000000000000000001/report?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z' \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-preview' \
--header 'accept: application/json'Response:
{
"formID": "000000000000000000000001",
"statistics": {
"views": 12500,
"interactions": 3200,
"submits": 840,
"signups": 790
},
"statisticsByDevice": {
"desktop": {
"views": 8000,
"interactions": 2100,
"submits": 560,
"signups": 530
},
"mobile": {
"views": 4000,
"interactions": 1000,
"submits": 250,
"signups": 235
},
"tablet": {
"views": 500,
"interactions": 100,
"submits": 30,
"signups": 25
}
}
}Form periodic report
Use GET /api/forms/{formID}/report/periodic to retrieve time-bucketed statistics for a form within a date range.
Granularity is auto-determined from the date range. If the granularity query parameter is provided, it must match the auto-determined value or the request is rejected.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| from | string | Start of the date range (RFC3339, e.g. 2024-01-01T00:00:00Z) |
| to | string | End of the date range (RFC3339, e.g. 2024-01-31T23:59:59Z) |
| granularity | string | Time bucket granularity. One of hour, day, month, year |
Example: Get form periodic report
curl --request GET \
--url 'https://api.omnisend.com/api/forms/000000000000000000000001/report/periodic?from=2024-01-01T00:00:00Z&to=2024-01-07T23:59:59Z&granularity=day' \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-preview' \
--header 'accept: application/json'Response — one row per time bucket:
{
"formID": "000000000000000000000001",
"granularity": "day",
"rows": [
{
"period": "2024-01-01",
"statistics": {
"views": 1800,
"interactions": 450,
"submits": 120,
"signups": 110
}
},
{
"period": "2024-01-02",
"statistics": {
"views": 2100,
"interactions": 520,
"submits": 140,
"signups": 132
}
}
]
}Form contacts
Use GET /api/forms/{formID}/contacts to retrieve contacts who submitted a specific form.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Maximum number of contacts per page (default 250, max 250) |
| sort | string | Sort field. Currently only createdAt is supported |
| direction | string | Sort direction. asc or desc (default desc) |
| after | string | Opaque cursor for fetching the next page |
| before | string | Opaque cursor for fetching the previous page |
Contacts are ordered by contact creation time embedded in the contact ID. The response date field reflects when the contact submitted this form (signup time) and may differ from the sort key for existing subscribers.
Contact fields
| Field | Description |
|---|---|
| id | Contact identifier |
| Contact email address | |
| phoneNumber | Contact phone number |
| firstName | First name |
| lastName | Last name |
| country | Country |
| gender | Gender |
| discount | Discount code received |
| date | Submission date |
| customProperties | Array of custom properties collected by the form |
Example: Get form contacts
curl --request GET \
--url 'https://api.omnisend.com/api/forms/000000000000000000000001/contacts?limit=50' \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-preview' \
--header 'accept: application/json'To paginate through results, use the after cursor from the previous response:
curl --request GET \
--url 'https://api.omnisend.com/api/forms/000000000000000000000001/contacts?limit=50&after=eyJpZCI6ImNhbXAtNDU2In0' \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-preview' \
--header 'accept: application/json'A/B setup reports
Use GET /api/forms/{formID}/ab-setup/reports to retrieve all completed A/B setup reports for a form.
Only A/B setups that have already completed are included. If the form has no completed A/B setups, the endpoint responds with 404 Not Found.
Report fields
| Field | Description |
|---|---|
| abSetupID | Identifier of the A/B setup |
| status | Status of the A/B setup |
| startedAt | When the A/B setup started |
| completedAt | When the A/B setup completed |
| winner | Name of the winning version |
| versionStatistics | Array of per-version statistics (see below) |
Each entry in versionStatistics contains:
| Field | Description |
|---|---|
| versionName | Name of the version |
| splitValue | Traffic split percentage allocated to the version |
| statistics | Per-version form metrics (see Metrics) |
Example: List completed A/B setup reports
curl --request GET \
--url 'https://api.omnisend.com/api/forms/000000000000000000000001/ab-setup/reports' \
--header 'Authorization: Omnisend-API-Key YOUR_API_KEY' \
--header 'Omnisend-Version: 2026-preview' \
--header 'accept: application/json'Response:
{
"reports": [
{
"abSetupID": "000000000000000000000010",
"status": "completed",
"startedAt": "2024-01-01T00:00:00Z",
"completedAt": "2024-01-15T00:00:00Z",
"winner": "Version A",
"versionStatistics": [
{
"versionName": "Version A",
"splitValue": 50,
"statistics": {
"views": 6000,
"interactions": 1500,
"submits": 420,
"signups": 400
}
},
{
"versionName": "Version B",
"splitValue": 50,
"statistics": {
"views": 6000,
"interactions": 1300,
"submits": 360,
"signups": 340
}
}
]
}
]
}