Introduction

The OpenEWS API enables Organizations and Governments to efficiently manage and disseminate early warning broadcasts to beneficiaries in disaster-prone areas. It provides robust tools for interacting with beneficiary data, crafting broadcast notification messages, and monitoring the performance of dissemination broadcasts. Built with scalability and flexibility in mind, OpenEWS supports integration with external systems, ensuring seamless communication and data interoperability.

The API follows the JSON:API standard, a specification for building APIs in a consistent and predictable manner. This ensures standardization in resource representation, error handling, and query parameters, making integration and development easier for your technical team.

This documentation is intended for developers, system integrators, and technical stakeholders working on early warning systems. By leveraging the OpenEWS API, you can automate processes such as beneficiary management, broadcast distribution, and reporting, empowering your organization to deliver timely and impactful alerts.

Making an HTTP Request

All API endpoints are accessible via HTTPS and adhere to RESTful principles. The API uses the JSON:API standard, meaning all requests and responses conform to a defined structure, including the use of specific top-level document fields (data, attributes, relationships, etc.).

The base URL for the API is: https://api.open-ews.org/v1/

Requests should include the following components:

HTTP Method: The API supports standard methods such as GET, POST, PATCH, and DELETE. Use the appropriate method based on the endpoint requirements.
Headers: Ensure the request includes the Authorization header with a valid API token and the Content-Type header set to application/vnd.api+json to comply with JSON:API standards.
Endpoint URL: Combine the base URL with the specific endpoint path to form the complete request URL.

Example HTTP Request

POST https://api.open-ews.org/v1/beneficiaries
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "phone_number": "+85510999999",
      "gender": "M",
      "iso_country_code": "KH"
    }
  }
}

Credentials

To access the OpenEWS API, you need an API token. Tokens authenticate your application and authorize access to API resources. Follow these steps to obtain and manage your API credentials:

Request an API Token: Log in to your OpenEWS account or contact your administrator to generate an API token.
Include the Token in Requests: Pass the token in the Authorization header of each API request using the format Bearer YOUR_API_TOKEN.
Token Security: Treat your token as sensitive information. Do not expose it in client-side code or share it publicly.
Regenerate or Revoke Tokens: If your token is compromised or needs to be updated, regenerate it from your account settings or by contacting the administrator.

Example Authorization Header

Authorization: Bearer YOUR_API_TOKEN

Filtering

OpenEWS supports filtering of resources using query parameters. Filters are passed using the following format:

?filter[$attribute][$operator]=value

You can combine multiple filters by adding additional filter[...] query parameters.

Filtering operators vary depending on the attribute type.

String Type Operators

For attributes of type string, the following operators are supported:

Operator	Description
`eq`	Equals the specified value
`not_eq`	Does not equal the specified value
`contains`	Contains the specified substring
`not_contains`	Does not contain the specified substring
`starts_with`	Starts with the specified substring
`in`	Matches any of the specified values (array)
`not_in`	Does not match any of the specified values
`is_null`	Checks if the value is null (`true` or `false`)

Examples:

GET https://api.open-ews.org/v1/beneficiaries?filter[phone_number][starts_with]=855
GET https://api.open-ews.org/v1/beneficiaries?filter[gender][in][]=M&filter[gender][in][]=F
GET https://api.open-ews.org/v1/beneficiaries?filter[gender][is_null]=true

Value Type Operators (e.g., integers, floats, dates)

Use these for numeric or comparable types (e.g., created_at):

Operator	Description
`eq`	Equals the specified value
`not_eq`	Does not equal the specified value
`gt`	Greater than the specified value
`gteq`	Greater than or equal to the specified value
`lt`	Less than the specified value
`lteq`	Less than or equal to the specified value
`between`	Between two values (inclusive), passed as an array
`is_null`	Checks if the value is null (`true` or `false`)

Examples:

GET https://api.open-ews.org/v1/beneficiaries?filter[created_at][between][]=2025-04-01&filter[created_at][between][]=2025-04-30
GET https://api.open-ews.org/v1/beneficiaries?filter[created_at][gteq]=2025-04-01

Accounts

Fetch account settings

This endpoint can be used to return account settings for the authorized account.

Request

Endpoint

GET /v1/account

GET https://api.open-ews.org/v1/account

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "64",
    "type": "account",
    "attributes": {
      "created_at": "2025-06-12T13:11:14Z",
      "updated_at": "2025-06-12T13:11:14Z",
      "somleng_account_sid": null,
      "somleng_auth_token": null
    }
  }
}

Beneficiaries

List all active beneficiaries

Request

Endpoint

GET /v1/beneficiaries

GET https://api.open-ews.org/v1/beneficiaries?filter[status][eq]=active

Parameters

{
  "filter": {
    "status": {
      "eq": "active"
    }
  }
}

Name	Description
filter[phone_number][$operator]	The phone number of the beneficiary.
filter[status][$operator]	Must be one of `active`, `disabled`.
filter[gender][$operator]	Must be one of `M` or `F`.
filter[disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": [
    {
      "id": "47",
      "type": "beneficiary",
      "attributes": {
        "created_at": "2025-06-12T13:11:14Z",
        "updated_at": "2025-06-12T13:11:14Z",
        "phone_number": "855972345726",
        "gender": null,
        "status": "active",
        "disability_status": null,
        "iso_language_code": null,
        "date_of_birth": null,
        "iso_country_code": "KH",
        "metadata": {}
      },
      "relationships": {
        "addresses": {
          "data": []
        },
        "groups": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/beneficiaries?filter%5Bstatus%5D%5Beq%5D=active&page%5Bbefore%5D=47",
    "next": null
  }
}

Filter beneficiaries

Request

Endpoint

GET /v1/beneficiaries

GET https://api.open-ews.org/v1/beneficiaries?filter[created_at][gt]=2025-06-08T13%3A11%3A14Z&amp;filter[gender][eq]=F

Parameters

{
  "filter": {
    "created_at": {
      "gt": "2025-06-08T13:11:14Z"
    },
    "gender": {
      "eq": "F"
    }
  }
}

Name	Description
filter[phone_number][$operator]	The phone number of the beneficiary.
filter[status][$operator]	Must be one of `active`, `disabled`.
filter[gender][$operator]	Must be one of `M` or `F`.
filter[disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": [
    {
      "id": "50",
      "type": "beneficiary",
      "attributes": {
        "created_at": "2025-06-12T13:11:14Z",
        "updated_at": "2025-06-12T13:11:14Z",
        "phone_number": "855972345729",
        "gender": "F",
        "status": "active",
        "disability_status": null,
        "iso_language_code": null,
        "date_of_birth": null,
        "iso_country_code": "KH",
        "metadata": {}
      },
      "relationships": {
        "addresses": {
          "data": []
        },
        "groups": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/beneficiaries?filter%5Bcreated_at%5D%5Bgt%5D=2025-06-08T13%3A11%3A14Z&filter%5Bgender%5D%5Beq%5D=F&page%5Bbefore%5D=50",
    "next": null
  }
}

Create a beneficiary

Request

Endpoint

POST /v1/beneficiaries

POST https://api.open-ews.org/v1/beneficiaries

Parameters

{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "phone_number": "+85510999999",
      "iso_language_code": "khm",
      "gender": "M",
      "date_of_birth": "1990-01-01",
      "metadata": {
        "my_custom_property": "my_custom_property_value"
      },
      "iso_country_code": "KH",
      "disability_status": "normal"
    }
  }
}

Name	Description
data[type] required	Must be `beneficiary`
data[attributes][phone_number] required	Phone number in E.164 format.
data[attributes][iso_country_code] required	The ISO 3166-1 country code of the beneficiary.
data[attributes][iso_language_code]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][gender]	Must be one of `M` or `F`.
data[attributes][status]	If supplied, must be one of `active`, `disabled`. Only beneficiaries with active status are considered when creating a broadcast.
data[attributes][disability_status]	If supplied, must be one of `normal`, `disabled`.
data[attributes][date_of_birth]	Date of birth in `YYYY-MM-DD` format.
data[attributes][metadata]	Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.
data[attributes][address][iso_region_code]	The ISO 3166-2 region code of the address
data[attributes][address][administrative_division_level_2_code]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][address][administrative_division_level_2_name]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][address][administrative_division_level_3_code]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][address][administrative_division_level_3_name]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][address][administrative_division_level_4_code]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][address][administrative_division_level_4_name]	The forth-level administrative subdivision name of the address (e.g. village name)
data[relationships][groups][data.*.type]	Must be `beneficiary_group`
data[relationships][groups][data.*.id]	The unique ID of the beneficiary group

Response

location: https://api.open-ews.org/v1/beneficiaries/56
201 Created

{
  "data": {
    "id": "56",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "85510999999",
      "gender": "M",
      "status": "active",
      "disability_status": "normal",
      "iso_language_code": "khm",
      "date_of_birth": "1990-01-01",
      "iso_country_code": "KH",
      "metadata": {
        "my_custom_property": "my_custom_property_value"
      }
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": []
      }
    }
  },
  "included": []
}

Create a beneficiary with an address

Request

Endpoint

POST /v1/beneficiaries

POST https://api.open-ews.org/v1/beneficiaries

Parameters

{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "phone_number": "+85510999999",
      "iso_country_code": "KH",
      "address": {
        "iso_region_code": "KH-1",
        "administrative_division_level_2_code": "0102",
        "administrative_division_level_2_name": "Mongkol Borei",
        "administrative_division_level_3_code": "010201",
        "administrative_division_level_3_name": "Banteay Neang",
        "administrative_division_level_4_code": "01020101",
        "administrative_division_level_4_name": "Ou Thum"
      }
    }
  }
}

Name	Description
data[type] required	Must be `beneficiary`
data[attributes][phone_number] required	Phone number in E.164 format.
data[attributes][iso_country_code] required	The ISO 3166-1 country code of the beneficiary.
data[attributes][iso_language_code]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][gender]	Must be one of `M` or `F`.
data[attributes][status]	If supplied, must be one of `active`, `disabled`. Only beneficiaries with active status are considered when creating a broadcast.
data[attributes][disability_status]	If supplied, must be one of `normal`, `disabled`.
data[attributes][date_of_birth]	Date of birth in `YYYY-MM-DD` format.
data[attributes][metadata]	Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.
data[attributes][address][iso_region_code]	The ISO 3166-2 region code of the address
data[attributes][address][administrative_division_level_2_code]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][address][administrative_division_level_2_name]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][address][administrative_division_level_3_code]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][address][administrative_division_level_3_name]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][address][administrative_division_level_4_code]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][address][administrative_division_level_4_name]	The forth-level administrative subdivision name of the address (e.g. village name)
data[relationships][groups][data.*.type]	Must be `beneficiary_group`
data[relationships][groups][data.*.id]	The unique ID of the beneficiary group

Response

location: https://api.open-ews.org/v1/beneficiaries/57
201 Created

{
  "data": {
    "id": "57",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "85510999999",
      "gender": null,
      "status": "active",
      "disability_status": null,
      "iso_language_code": null,
      "date_of_birth": null,
      "iso_country_code": "KH",
      "metadata": {}
    },
    "relationships": {
      "addresses": {
        "data": [
          {
            "id": "15",
            "type": "beneficiary_address"
          }
        ]
      },
      "groups": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "15",
      "type": "beneficiary_address",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "iso_region_code": "KH-1",
        "administrative_division_level_2_code": "0102",
        "administrative_division_level_2_name": "Mongkol Borei",
        "administrative_division_level_3_code": "010201",
        "administrative_division_level_3_name": "Banteay Neang",
        "administrative_division_level_4_code": "01020101",
        "administrative_division_level_4_name": "Ou Thum"
      }
    }
  ]
}

Create a beneficiary and add them to a group

Request

Endpoint

POST /v1/beneficiaries

POST https://api.open-ews.org/v1/beneficiaries

Parameters

{
  "data": {
    "type": "beneficiary",
    "attributes": {
      "phone_number": "+85510999999",
      "iso_country_code": "KH"
    },
    "relationships": {
      "groups": {
        "data": [
          {
            "type": "beneficiary_group",
            "id": 21
          }
        ]
      }
    }
  }
}

Name	Description
data[type] required	Must be `beneficiary`
data[attributes][phone_number] required	Phone number in E.164 format.
data[attributes][iso_country_code] required	The ISO 3166-1 country code of the beneficiary.
data[attributes][iso_language_code]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][gender]	Must be one of `M` or `F`.
data[attributes][status]	If supplied, must be one of `active`, `disabled`. Only beneficiaries with active status are considered when creating a broadcast.
data[attributes][disability_status]	If supplied, must be one of `normal`, `disabled`.
data[attributes][date_of_birth]	Date of birth in `YYYY-MM-DD` format.
data[attributes][metadata]	Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.
data[attributes][address][iso_region_code]	The ISO 3166-2 region code of the address
data[attributes][address][administrative_division_level_2_code]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][address][administrative_division_level_2_name]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][address][administrative_division_level_3_code]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][address][administrative_division_level_3_name]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][address][administrative_division_level_4_code]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][address][administrative_division_level_4_name]	The forth-level administrative subdivision name of the address (e.g. village name)
data[relationships][groups][data.*.type]	Must be `beneficiary_group`
data[relationships][groups][data.*.id]	The unique ID of the beneficiary group

Response

location: https://api.open-ews.org/v1/beneficiaries/58
201 Created

{
  "data": {
    "id": "58",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "85510999999",
      "gender": null,
      "status": "active",
      "disability_status": null,
      "iso_language_code": null,
      "date_of_birth": null,
      "iso_country_code": "KH",
      "metadata": {}
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": [
          {
            "id": "21",
            "type": "beneficiary_group"
          }
        ]
      }
    }
  },
  "included": []
}

Fetch a beneficiary

Request

Endpoint

GET /v1/beneficiaries/:id

GET https://api.open-ews.org/v1/beneficiaries/60

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "60",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "855972345734",
      "gender": null,
      "status": "active",
      "disability_status": null,
      "iso_language_code": null,
      "date_of_birth": null,
      "iso_country_code": "KH",
      "metadata": {}
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": []
      }
    }
  }
}

Update a beneficiary

Request

Endpoint

PATCH /v1/beneficiaries/:id

PATCH https://api.open-ews.org/v1/beneficiaries/61

Parameters

{
  "data": {
    "id": 61,
    "type": "beneficiary",
    "attributes": {
      "phone_number": "+85510999002",
      "gender": "F",
      "status": "disabled",
      "iso_language_code": "eng",
      "date_of_birth": "1990-01-01",
      "metadata": {
        "foo": "bar"
      }
    }
  }
}

Name	Description
data[id] required	The unique identifier of the beneficiary.
data[type] required	Must be `beneficiary`
data[attributes][phone_number]	Phone number in E.164 format.
data[attributes][iso_country_code]	The ISO 3166-1 country code of the beneficiary.
data[attributes][iso_language_code]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][gender]	Must be one of `M` or `F`.
data[attributes][status]	If supplied, must be one of `active`, `disabled`. Only beneficiaries with active status are considered when creating a broadcast.
data[attributes][disability_status]	If supplied, must be one of `normal`, `disabled`.
data[attributes][date_of_birth]	Date of birth in `YYYY-MM-DD` format.
data[attributes][metadata]	Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.

Response


200 OK

{
  "data": {
    "id": "61",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "85510999002",
      "gender": "F",
      "status": "disabled",
      "disability_status": null,
      "iso_language_code": "eng",
      "date_of_birth": "1990-01-01",
      "iso_country_code": "KH",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": []
      }
    }
  }
}

Disable a beneficiary

Request

Endpoint

PATCH /v1/beneficiaries/:id

PATCH https://api.open-ews.org/v1/beneficiaries/62

Parameters

{
  "data": {
    "id": 62,
    "type": "beneficiary",
    "attributes": {
      "status": "disabled"
    }
  }
}

Name	Description
data[id] required	The unique identifier of the beneficiary.
data[type] required	Must be `beneficiary`
data[attributes][phone_number]	Phone number in E.164 format.
data[attributes][iso_country_code]	The ISO 3166-1 country code of the beneficiary.
data[attributes][iso_language_code]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][gender]	Must be one of `M` or `F`.
data[attributes][status]	If supplied, must be one of `active`, `disabled`. Only beneficiaries with active status are considered when creating a broadcast.
data[attributes][disability_status]	If supplied, must be one of `normal`, `disabled`.
data[attributes][date_of_birth]	Date of birth in `YYYY-MM-DD` format.
data[attributes][metadata]	Set of key-value pairs that you can attach to the beneficiary. This can be useful for storing additional information about the beneficiary in a structured format.

Response


200 OK

{
  "data": {
    "id": "62",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "855972345735",
      "gender": null,
      "status": "disabled",
      "disability_status": null,
      "iso_language_code": null,
      "date_of_birth": null,
      "iso_country_code": "KH",
      "metadata": {}
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": []
      }
    }
  }
}

Fetch beneficiaries stats

This endpoint provides statistical insights into the beneficiaries managed within the OpenEWS system. This endpoint is particularly useful for generating reports, analyzing beneficiary data, and monitoring the scope of your early warning system.

Functionality

This endpoint returns aggregated statistics about the beneficiaries in your system. Common use cases include:

Counting the total number of beneficiaries.
Grouping beneficiaries by attributes such as location, gender, or address attributes.
Identifying trends or patterns in beneficiary data.

Parameters

The endpoint may accept query parameters to filter or group the data. Common parameters include:

Filters: Specify conditions for narrowing down the results. For example, you might filter beneficiaries by a specific region or status.
Group By: Group the statistics by a particular attribute such as gender, address, or disability_status.

Request

Endpoint

GET /v1/beneficiaries/stats

GET https://api.open-ews.org/v1/beneficiaries/stats?filter[gender][eq]=M&amp;filter[address.iso_region_code][eq]=KH-12&amp;group_by[]=iso_country_code&amp;group_by[]=address.iso_region_code&amp;group_by[]=address.administrative_division_level_2_code

Parameters

{
  "filter": {
    "gender": {
      "eq": "M"
    },
    "address.iso_region_code": {
      "eq": "KH-12"
    }
  },
  "group_by": [
    "iso_country_code",
    "address.iso_region_code",
    "address.administrative_division_level_2_code"
  ]
}

Name	Description
filter[phone_number][$operator]	The phone number of the beneficiary.
filter[status][$operator]	Must be one of `active`, `disabled`.
filter[gender][$operator]	Must be one of `M` or `F`.
filter[disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)
group_by required	An array of fields to group by. Supported fields: `gender`, `disability_status`, `iso_language_code`, `iso_country_code`, `address.iso_region_code`, `address.administrative_division_level_2_code`, `address.administrative_division_level_2_name`, `address.administrative_division_level_3_code`, `address.administrative_division_level_3_name`, `address.administrative_division_level_4_code`, `address.administrative_division_level_4_name`.

Response


200 OK

{
  "data": [
    {
      "id": "b01a97db57bf9b5ac36dcbc808db708ce53366304f25205d15c3df255130be60",
      "type": "stat",
      "attributes": {
        "result": {
          "iso_country_code": "KH",
          "address.iso_region_code": "KH-12",
          "address.administrative_division_level_2_code": "1201",
          "value": 1
        }
      }
    },
    {
      "id": "b331804f9e357d3f4a65454256a4b12b926840b60c56fbfa393b9804de3482f6",
      "type": "stat",
      "attributes": {
        "result": {
          "iso_country_code": "KH",
          "address.iso_region_code": "KH-12",
          "address.administrative_division_level_2_code": "1202",
          "value": 2
        }
      }
    }
  ]
}

Delete a beneficiary

Request

Endpoint

DELETE /v1/beneficiaries/:id

DELETE https://api.open-ews.org/v1/beneficiaries/72

Parameters

None known.

Response


204 No Content

List all addresses for a beneficiary

Request

Endpoint

GET /v1/beneficiaries/:beneficiary_id/addresses

GET https://api.open-ews.org/v1/beneficiaries/73/addresses

Parameters

None known.

Response


200 OK

{
  "data": [
    {
      "id": "24",
      "type": "beneficiary_address",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "iso_region_code": "KH-1",
        "administrative_division_level_2_code": "0102",
        "administrative_division_level_2_name": "Mongkol Borei",
        "administrative_division_level_3_code": "010201",
        "administrative_division_level_3_name": "Banteay Neang",
        "administrative_division_level_4_code": "01020102",
        "administrative_division_level_4_name": "Phnum"
      }
    },
    {
      "id": "23",
      "type": "beneficiary_address",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "iso_region_code": "KH-1",
        "administrative_division_level_2_code": "0102",
        "administrative_division_level_2_name": "Mongkol Borei",
        "administrative_division_level_3_code": "010201",
        "administrative_division_level_3_name": "Banteay Neang",
        "administrative_division_level_4_code": "01020101",
        "administrative_division_level_4_name": "Ou Thum"
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/beneficiaries/73/addresses?page%5Bbefore%5D=24",
    "next": null
  }
}

Create an address for a beneficiary

Request

Endpoint

POST /v1/beneficiaries/:beneficiary_id/addresses

POST https://api.open-ews.org/v1/beneficiaries/75/addresses

Parameters

{
  "data": {
    "type": "beneficiary_address",
    "attributes": {
      "iso_region_code": "KH-1",
      "administrative_division_level_2_code": "0102",
      "administrative_division_level_2_name": "Mongkol Borei",
      "administrative_division_level_3_code": "010201",
      "administrative_division_level_3_name": "Banteay Neang",
      "administrative_division_level_4_code": "01020101",
      "administrative_division_level_4_name": "Ou Thum"
    }
  }
}

Name	Description
data[type] required	Must be `beneficiary_address`
data[attributes][iso_region_code] required	The ISO 3166-2 region code of the address
data[attributes][administrative_division_level_2_code]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][administrative_division_level_2_name]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][administrative_division_level_3_code]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][administrative_division_level_3_name]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][administrative_division_level_4_code]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][administrative_division_level_4_name]	The forth-level administrative subdivision name of the address (e.g. village name)

Response

location: /v1/beneficiaries/75/addresses/26
201 Created

{
  "data": {
    "id": "26",
    "type": "beneficiary_address",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "iso_region_code": "KH-1",
      "administrative_division_level_2_code": "0102",
      "administrative_division_level_2_name": "Mongkol Borei",
      "administrative_division_level_3_code": "010201",
      "administrative_division_level_3_name": "Banteay Neang",
      "administrative_division_level_4_code": "01020101",
      "administrative_division_level_4_name": "Ou Thum"
    }
  }
}

Fetch an address for a beneficiary

Request

Endpoint

GET /v1/beneficiaries/:beneficiary_id/addresses/:id

GET https://api.open-ews.org/v1/beneficiaries/76/addresses/27

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "27",
    "type": "beneficiary_address",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "iso_region_code": "KH-1",
      "administrative_division_level_2_code": "0102",
      "administrative_division_level_2_name": "Mongkol Borei",
      "administrative_division_level_3_code": "010201",
      "administrative_division_level_3_name": "Banteay Neang",
      "administrative_division_level_4_code": "01020101",
      "administrative_division_level_4_name": "Ou Thum"
    }
  }
}

Delete an address for a beneficiary

Request

Endpoint

DELETE /v1/beneficiaries/:beneficiary_id/addresses/:id

DELETE https://api.open-ews.org/v1/beneficiaries/77/addresses/28

Parameters

None known.

Response


204 No Content

Beneficiary Groups

The Beneficiary Groups endpoint allows developers to programmatically organize beneficiaries into logical groups for targeted message delivery. This is particularly useful when building workflows that require sending notifications to a specific group of beneficiaries, such as response teams in addition to those matched dynamically by filters.

Beneficiary Groups are not required for sending targeted notifications. For most use cases, it's recommended to use broadcasts with beneficiary filters, which dynamically match recipients based on defined criteria. Beneficiary Groups, by contrast, are static collections of specific beneficiaries. They're useful when you need to repeatedly target a fixed set of individuals such as a response team or a predefined community, in addition to those matched dynamically by filters.

Through this API, you can create, list, update, and delete groups, as well as manage their relationships with individual beneficiaries.

List all groups

Request

Endpoint

GET /v1/beneficiary_groups

GET https://api.open-ews.org/v1/beneficiary_groups

Parameters

Name	Description
filter[name][$operator]	A friendly name for the group.

Response


200 OK

{
  "data": [
    {
      "id": "23",
      "type": "beneficiary_group",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "name": "Other Group"
      },
      "relationships": {
        "members": {
          "data": []
        }
      }
    },
    {
      "id": "22",
      "type": "beneficiary_group",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "name": "My Group"
      },
      "relationships": {
        "members": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/beneficiary_groups?page%5Bbefore%5D=23",
    "next": null
  }
}

Fetch a group

Request

Endpoint

GET /v1/beneficiary_groups/:id

GET https://api.open-ews.org/v1/beneficiary_groups/27

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "27",
    "type": "beneficiary_group",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "name": "My Group"
    },
    "relationships": {
      "members": {
        "data": []
      }
    }
  }
}

Create a group

Request

Endpoint

POST /v1/beneficiary_groups

POST https://api.open-ews.org/v1/beneficiary_groups

Parameters

{
  "data": {
    "type": "beneficiary_group",
    "attributes": {
      "name": "My Group"
    }
  }
}

Name	Description
data[type] required	Must be `beneficiary_group`
data[attributes][name] required	A friendly name for the group.

Response

location: https://api.open-ews.org/v1/beneficiary_groups/28
201 Created

{
  "data": {
    "id": "28",
    "type": "beneficiary_group",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "name": "My Group"
    },
    "relationships": {
      "members": {
        "data": []
      }
    }
  }
}

Update a group

Request

Endpoint

PATCH /v1/beneficiary_groups/:id

PATCH https://api.open-ews.org/v1/beneficiary_groups/29

Parameters

{
  "data": {
    "id": 29,
    "type": "beneficiary_group",
    "attributes": {
      "name": "VIP Group"
    }
  }
}

Name	Description
data[id] required	The unique identifier of the beneficiary_group.
data[type] required	Must be `beneficiary_group`
data[attributes][name] required	A friendly name for the group.

Response


200 OK

{
  "data": {
    "id": "29",
    "type": "beneficiary_group",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "name": "VIP Group"
    },
    "relationships": {
      "members": {
        "data": []
      }
    }
  }
}

Delete a group

Request

Endpoint

DELETE /v1/beneficiary_groups/:id

DELETE https://api.open-ews.org/v1/beneficiary_groups/30

Parameters

None known.

Response


204 No Content

List all members of a group

Request

Endpoint

GET /v1/beneficiary_groups/:beneficiary_group_id/members

GET https://api.open-ews.org/v1/beneficiary_groups/31/members

Parameters

Name	Description
filter[phone_number][$operator]	The phone number of the beneficiary.
filter[status][$operator]	Must be one of `active`, `disabled`.
filter[gender][$operator]	Must be one of `M` or `F`.
filter[disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": [
    {
      "id": "79",
      "type": "beneficiary",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345752",
        "gender": null,
        "status": "active",
        "disability_status": null,
        "iso_language_code": null,
        "date_of_birth": null,
        "iso_country_code": "KH",
        "metadata": {}
      },
      "relationships": {
        "addresses": {
          "data": []
        },
        "groups": {
          "data": [
            {
              "id": "31",
              "type": "beneficiary_group"
            }
          ]
        }
      }
    },
    {
      "id": "78",
      "type": "beneficiary",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345751",
        "gender": null,
        "status": "active",
        "disability_status": null,
        "iso_language_code": null,
        "date_of_birth": null,
        "iso_country_code": "KH",
        "metadata": {}
      },
      "relationships": {
        "addresses": {
          "data": []
        },
        "groups": {
          "data": [
            {
              "id": "31",
              "type": "beneficiary_group"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/beneficiary_groups/31/members?page%5Bbefore%5D=79",
    "next": null
  }
}

Fetch a member of a group

Request

Endpoint

GET /v1/beneficiary_groups/:beneficiary_group_id/members/:id

GET https://api.open-ews.org/v1/beneficiary_groups/34/members/83

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "83",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "855972345756",
      "gender": null,
      "status": "active",
      "disability_status": null,
      "iso_language_code": null,
      "date_of_birth": null,
      "iso_country_code": "KH",
      "metadata": {}
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": [
          {
            "id": "34",
            "type": "beneficiary_group"
          }
        ]
      }
    }
  }
}

Add a beneficiary to a group

Request

Endpoint

POST /v1/beneficiary_groups/:beneficiary_group_id/members

POST https://api.open-ews.org/v1/beneficiary_groups/35/members

Parameters

{
  "data": {
    "type": "beneficiary_group_member",
    "attributes": {
      "beneficiary_id": 84
    }
  }
}

Name	Description
data[type] required	Must be `beneficiary_group_member`
data[attributes][beneficiary_id] required	The unique identifier of the `beneficiary`

Response

location: https://api.open-ews.org/v1/beneficiaries/84
201 Created

{
  "data": {
    "id": "84",
    "type": "beneficiary",
    "attributes": {
      "created_at": "2025-06-12T13:11:15Z",
      "updated_at": "2025-06-12T13:11:15Z",
      "phone_number": "855972345757",
      "gender": null,
      "status": "active",
      "disability_status": null,
      "iso_language_code": null,
      "date_of_birth": null,
      "iso_country_code": "KH",
      "metadata": {}
    },
    "relationships": {
      "addresses": {
        "data": []
      },
      "groups": {
        "data": [
          {
            "id": "35",
            "type": "beneficiary_group"
          }
        ]
      }
    }
  }
}

Remove a beneficiary from a group

Request

Endpoint

DELETE /v1/beneficiary_groups/:beneficiary_group_id/members/:id

DELETE https://api.open-ews.org/v1/beneficiary_groups/37/members/86

Parameters

None known.

Response


204 No Content

Fetch stats for group members

This endpoint provides statistical insights into the beneficiaries within the given group.

Functionality

This endpoint returns aggregated statistics about the beneficiaries in your group. Common use cases include:

Counting the total number of beneficiaries within the group.
Grouping beneficiaries by attributes such as location, gender, or address attributes.
Identifying trends or patterns in the group.

Parameters

The endpoint may accept query parameters to filter or group the data. Common parameters include:

Filters: Specify conditions for narrowing down the results. For example, you might filter beneficiaries by a specific region or status.
Group By: Group the statistics by a particular attribute such as gender, address, or disability_status.

Request

Endpoint

GET /v1/beneficiary_groups/:beneficiary_group_id/members/stats

GET https://api.open-ews.org/v1/beneficiary_groups/38/members/stats?group_by[]=gender

Parameters

{
  "group_by": [
    "gender"
  ]
}

Name	Description
filter[phone_number][$operator]	The phone number of the beneficiary.
filter[status][$operator]	Must be one of `active`, `disabled`.
filter[gender][$operator]	Must be one of `M` or `F`.
filter[disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)
group_by required	An array of fields to group by. Supported fields: `gender`, `disability_status`, `iso_language_code`, `iso_country_code`, `address.iso_region_code`, `address.administrative_division_level_2_code`, `address.administrative_division_level_2_name`, `address.administrative_division_level_3_code`, `address.administrative_division_level_3_name`, `address.administrative_division_level_4_code`, `address.administrative_division_level_4_name`.

Response


200 OK

{
  "data": [
    {
      "id": "f67ab10ad4e4c53121b6a5fe4da9c10ddee905b978d3788d2723d7bfacbe28a9",
      "type": "stat",
      "attributes": {
        "result": {
          "gender": "F",
          "value": 1
        }
      }
    },
    {
      "id": "08f271887ce94707da822d5263bae19d5519cb3614e0daedc4c7ce5dab7473f1",
      "type": "stat",
      "attributes": {
        "result": {
          "gender": "M",
          "value": 2
        }
      }
    }
  ]
}

Notifications

The Notifications API allows you to view and analyze the individual notifications that are sent to beneficiaries as part of a broadcast.

A Notification represents a planned message to a single beneficiary, linked to a specific Broadcast. Each Notification may have one or more attempts, which track the actual transmission process.

This API provides endpoints to:

List notifications associated with a specific broadcast.
Retrieve statistics for all notifications under a broadcast, such as:
- Delivery success rate
- Number of attempts
- Time to delivery

This API is ideal for implementers who need visibility into message distribution, system performance, and delivery outcomes at the individual recipient level.

List all notifications for a broadcast

Request

Endpoint

GET /v1/broadcasts/:broadcast_id/notifications

GET https://api.open-ews.org/v1/broadcasts/45/notifications

Parameters

Name	Description
filter[status][$operator]	Must be one of `pending`, `failed`, `succeeded`.
filter[delivery_attempts_count][$operator]	Number of delivery attempts
filter[created_at][$operator]	The ISO 8601 timestamp of when the notification was created.
filter[completed_at][$operator]	The ISO 8601 timestamp of when the notification was completed.
filter[beneficiary.phone_number][$operator]	The phone number of the beneficiary.
filter[beneficiary.status][$operator]	Must be one of `active`, `disabled`.
filter[beneficiary.gender][$operator]	Must be one of `M` or `F`.
filter[beneficiary.disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[beneficiary.date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[beneficiary.iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[beneficiary.iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[beneficiary.created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[beneficiary.address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[beneficiary.address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[beneficiary.address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[beneficiary.address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[beneficiary.address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[beneficiary.address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[beneficiary.address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": [
    {
      "id": "29",
      "type": "notification",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345766",
        "status": "pending",
        "delivery_attempts_count": 0
      },
      "relationships": {
        "broadcast": {
          "data": {
            "id": "45",
            "type": "broadcast"
          }
        },
        "beneficiary": {
          "data": {
            "id": "93",
            "type": "beneficiary"
          }
        }
      }
    },
    {
      "id": "28",
      "type": "notification",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345765",
        "status": "pending",
        "delivery_attempts_count": 0
      },
      "relationships": {
        "broadcast": {
          "data": {
            "id": "45",
            "type": "broadcast"
          }
        },
        "beneficiary": {
          "data": {
            "id": "92",
            "type": "beneficiary"
          }
        }
      }
    },
    {
      "id": "27",
      "type": "notification",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345764",
        "status": "pending",
        "delivery_attempts_count": 0
      },
      "relationships": {
        "broadcast": {
          "data": {
            "id": "45",
            "type": "broadcast"
          }
        },
        "beneficiary": {
          "data": {
            "id": "91",
            "type": "beneficiary"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/broadcasts/45/notifications?page%5Bbefore%5D=29",
    "next": null
  }
}

Filter notifications

Request

Endpoint

GET /v1/broadcasts/:broadcast_id/notifications

GET https://api.open-ews.org/v1/broadcasts/47/notifications?filter[status][eq]=succeeded&amp;filter[completed_at][gt]=2025-06-12T12%3A21%3A16Z

Parameters

{
  "filter": {
    "status": {
      "eq": "succeeded"
    },
    "completed_at": {
      "gt": "2025-06-12T12:21:16Z"
    }
  }
}

Name	Description
filter[status][$operator]	Must be one of `pending`, `failed`, `succeeded`.
filter[delivery_attempts_count][$operator]	Number of delivery attempts
filter[created_at][$operator]	The ISO 8601 timestamp of when the notification was created.
filter[completed_at][$operator]	The ISO 8601 timestamp of when the notification was completed.
filter[beneficiary.phone_number][$operator]	The phone number of the beneficiary.
filter[beneficiary.status][$operator]	Must be one of `active`, `disabled`.
filter[beneficiary.gender][$operator]	Must be one of `M` or `F`.
filter[beneficiary.disability_status][$operator]	Must be one of `normal`, `disabled`.
filter[beneficiary.date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
filter[beneficiary.iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[beneficiary.iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
filter[beneficiary.created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
filter[beneficiary.address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
filter[beneficiary.address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
filter[beneficiary.address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
filter[beneficiary.address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[beneficiary.address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[beneficiary.address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[beneficiary.address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": [
    {
      "id": "32",
      "type": "notification",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345769",
        "status": "succeeded",
        "delivery_attempts_count": 0
      },
      "relationships": {
        "broadcast": {
          "data": {
            "id": "47",
            "type": "broadcast"
          }
        },
        "beneficiary": {
          "data": {
            "id": "96",
            "type": "beneficiary"
          }
        }
      }
    },
    {
      "id": "31",
      "type": "notification",
      "attributes": {
        "created_at": "2025-06-12T13:11:15Z",
        "updated_at": "2025-06-12T13:11:15Z",
        "phone_number": "855972345768",
        "status": "succeeded",
        "delivery_attempts_count": 0
      },
      "relationships": {
        "broadcast": {
          "data": {
            "id": "47",
            "type": "broadcast"
          }
        },
        "beneficiary": {
          "data": {
            "id": "95",
            "type": "beneficiary"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/broadcasts/47/notifications?filter%5Bcompleted_at%5D%5Bgt%5D=2025-06-12T12%3A21%3A16Z&filter%5Bstatus%5D%5Beq%5D=succeeded&page%5Bbefore%5D=32",
    "next": null
  }
}

Fetch an notification

Request

Endpoint

GET /v1/broadcasts/:broadcast_id/notifications/:id

GET https://api.open-ews.org/v1/broadcasts/51/notifications/41

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "41",
    "type": "notification",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "phone_number": "855972345778",
      "status": "pending",
      "delivery_attempts_count": 0
    },
    "relationships": {
      "broadcast": {
        "data": {
          "id": "51",
          "type": "broadcast"
        }
      },
      "beneficiary": {
        "data": {
          "id": "105",
          "type": "beneficiary"
        }
      }
    }
  }
}

Fetch notifications stats

This endpoint provides statistical insights into the notifications under a broadcast managed within the OpenEWS system. This endpoint is particularly useful for generating reports, analyzing notification data, and monitoring the scope of your early warning system.

Functionality

This endpoint returns aggregated statistics about the notifications under a broadcast in your system. Common use cases include:

Counting the total number of notifications.
Grouping notifications by beneficiary's attributes such as location or gender.
Identifying trends or patterns in notification data.

Parameters

The endpoint may accept query parameters to filter or group the data. Common parameters include:

Filters: Specify conditions for narrowing down the results. For example, you might filter notifications by a specific status or beneficiary's fields.
Group By: Group the statistics by a particular attribute such as status, or beneficiary's fields.

Request

Endpoint

GET /v1/broadcasts/:broadcast_id/notifications/stats

GET https://api.open-ews.org/v1/broadcasts/52/notifications/stats?filter[status][eq]=succeeded&amp;group_by[]=beneficiary.gender

Parameters

{
  "filter": {
    "status": {
      "eq": "succeeded"
    }
  },
  "group_by": [
    "beneficiary.gender"
  ]
}

Name	Description
filter[status]	Must be one of `pending`, `failed`, `succeeded`.
filter[delivery_attempts_count]	Number of delivery attempts
filter[created_at]	The ISO 8601 timestamp of when the notification was created.
filter[completed_at]	The ISO 8601 timestamp of when the notification was completed.
filter[beneficiary.phone_number]	The phone number of the beneficiary.
filter[beneficiary.status]	Must be one of `active`, `disabled`.
filter[beneficiary.gender]	Must be one of `M` or `F`.
filter[beneficiary.disability_status]	Must be one of `normal`, `disabled`.
filter[beneficiary.date_of_birth]	Date of birth in `YYYY-MM-DD` format.
filter[beneficiary.iso_language_code]	The ISO 639-2 alpha-3 language code of the beneficiary.
filter[beneficiary.iso_country_code]	The ISO 3166-1 country code of the beneficiary.
filter[beneficiary.created_at]	The ISO 8601 timestamp of when the beneficiary was created.
filter[beneficiary.address.iso_region_code]	The ISO 3166-2 region code of the address
filter[beneficiary.address.administrative_division_level_2_code]	The second-level administrative subdivision code of the address (e.g. district code)
filter[beneficiary.address.administrative_division_level_2_name]	The second-level administrative subdivision name of the address (e.g. district name)
filter[beneficiary.address.administrative_division_level_3_code]	The third-level administrative subdivision code of the address (e.g. commune code)
filter[beneficiary.address.administrative_division_level_3_name]	The third-level administrative subdivision name of the address (e.g. commune name)
filter[beneficiary.address.administrative_division_level_4_code]	The forth-level administrative subdivision code of the address (e.g. village code)
filter[beneficiary.address.administrative_division_level_4_name]	The forth-level administrative subdivision name of the address (e.g. village name)
group_by required	An array of fields to group by. Supported fields: `status`, `beneficiary.gender`, `beneficiary.disability_status`, `beneficiary.iso_language_code`, `beneficiary.iso_country_code`, `beneficiary.address.iso_region_code`, `beneficiary.address.administrative_division_level_2_code`, `beneficiary.address.administrative_division_level_2_name`, `beneficiary.address.administrative_division_level_3_code`, `beneficiary.address.administrative_division_level_3_name`, `beneficiary.address.administrative_division_level_4_code`, `beneficiary.address.administrative_division_level_4_name`.

Response


200 OK

{
  "data": [
    {
      "id": "f67ab10ad4e4c53121b6a5fe4da9c10ddee905b978d3788d2723d7bfacbe28a9",
      "type": "stat",
      "attributes": {
        "result": {
          "beneficiary.gender": "F",
          "value": 2
        }
      }
    },
    {
      "id": "08f271887ce94707da822d5263bae19d5519cb3614e0daedc4c7ce5dab7473f1",
      "type": "stat",
      "attributes": {
        "result": {
          "beneficiary.gender": "M",
          "value": 2
        }
      }
    }
  ]
}

Broadcasts

List all broadcasts

Request

Endpoint

GET /v1/broadcasts

GET https://api.open-ews.org/v1/broadcasts

Parameters

Name	Description
filter[status][$operator]	Must be one of `pending`, `queued`, `errored`, `running`, `stopped`, `completed`.
filter[channel][$operator]	Must be one of `voice`.
filter[created_at][$operator]	The ISO 8601 timestamp of when the broadcast was created.
filter[started_at][$operator]	The ISO 8601 timestamp of when the broadcast was started.
filter[completed_at][$operator]	The ISO 8601 timestamp of when the broadcast was completed.

Response


200 OK

{
  "data": [
    {
      "id": "53",
      "type": "broadcast",
      "attributes": {
        "created_at": "2025-06-12T13:11:16Z",
        "updated_at": "2025-06-12T13:11:16Z",
        "channel": "voice",
        "audio_url": null,
        "metadata": {},
        "beneficiary_filter": {},
        "status": "pending",
        "error_code": null
      },
      "relationships": {
        "beneficiary_groups": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/broadcasts?page%5Bbefore%5D=53",
    "next": null
  }
}

Filter broadcasts

Request

Endpoint

GET /v1/broadcasts

GET https://api.open-ews.org/v1/broadcasts?filter[status][eq]=running&amp;filter[started_at][gt]=2025-06-12T08%3A11%3A16Z

Parameters

{
  "filter": {
    "status": {
      "eq": "running"
    },
    "started_at": {
      "gt": "2025-06-12T08:11:16Z"
    }
  }
}

Name	Description
filter[status][$operator]	Must be one of `pending`, `queued`, `errored`, `running`, `stopped`, `completed`.
filter[channel][$operator]	Must be one of `voice`.
filter[created_at][$operator]	The ISO 8601 timestamp of when the broadcast was created.
filter[started_at][$operator]	The ISO 8601 timestamp of when the broadcast was started.
filter[completed_at][$operator]	The ISO 8601 timestamp of when the broadcast was completed.

Response


200 OK

{
  "data": [
    {
      "id": "55",
      "type": "broadcast",
      "attributes": {
        "created_at": "2025-06-12T13:11:16Z",
        "updated_at": "2025-06-12T13:11:16Z",
        "channel": "voice",
        "audio_url": null,
        "metadata": {},
        "beneficiary_filter": {
          "gender": {
            "eq": "M"
          }
        },
        "status": "running",
        "error_code": null
      },
      "relationships": {
        "beneficiary_groups": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/broadcasts?filter%5Bstarted_at%5D%5Bgt%5D=2025-06-12T08%3A11%3A16Z&filter%5Bstatus%5D%5Beq%5D=running&page%5Bbefore%5D=55",
    "next": null
  }
}

Fetch a broadcast

Request

Endpoint

GET /v1/broadcasts/:id

GET https://api.open-ews.org/v1/broadcasts/58

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "58",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": null,
      "metadata": {},
      "beneficiary_filter": {},
      "status": "pending",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": []
      }
    }
  }
}

Create and start a broadcast

Request

Endpoint

POST /v1/broadcasts

POST https://api.open-ews.org/v1/broadcasts

Parameters

{
  "data": {
    "type": "broadcast",
    "attributes": {
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3",
      "status": "running",
      "beneficiary_filter": {
        "gender": {
          "eq": "M"
        },
        "address.iso_region_code": {
          "in": [
            "KH-1",
            "KH-2"
          ]
        }
      }
    }
  }
}

Name	Description
data[type] required	Must be `broadcast`
data[attributes][channel] required	Must be one of `voice`.
data[attributes][audio_url] required	A publicly available URL which contains the broadcast message.
data[attributes][status]	If supplied, must be `running`. This will create the broadcast and start it immediately.
data[attributes][metadata]	Set of key-value pairs that you can attach to the broadcast. This can be useful for storing additional information about the broadcast in a structured format.
data[attributes][beneficiary_filter][phone_number][$operator]	The phone number of the beneficiary.
data[attributes][beneficiary_filter][status][$operator]	Must be one of `active`, `disabled`.
data[attributes][beneficiary_filter][gender][$operator]	Must be one of `M` or `F`.
data[attributes][beneficiary_filter][disability_status][$operator]	Must be one of `normal`, `disabled`.
data[attributes][beneficiary_filter][date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
data[attributes][beneficiary_filter][iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][beneficiary_filter][iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
data[attributes][beneficiary_filter][created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
data[attributes][beneficiary_filter][address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
data[attributes][beneficiary_filter][address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][beneficiary_filter][address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][beneficiary_filter][address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][beneficiary_filter][address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][beneficiary_filter][address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][beneficiary_filter][address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)
data[relationships][beneficiary_groups][data.*.type]	Must be `beneficiary_group`
data[relationships][beneficiary_groups][data.*.id]	The unique ID of the beneficiary group

Response

location: https://api.open-ews.org/v1/broadcasts/59
201 Created

{
  "data": {
    "id": "59",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3",
      "metadata": {},
      "beneficiary_filter": {
        "gender": {
          "eq": "M"
        },
        "address.iso_region_code": {
          "in": [
            "KH-1",
            "KH-2"
          ]
        }
      },
      "status": "queued",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": []
      }
    }
  }
}

Create broadcast with a beneficiary group

When creating a broadcast, you can target one or more beneficiary groups in addition to or instead of using a beneficiary filter. Beneficiaries included through groups will receive notifications with higher priority than those matched solely by the filter. This is especially useful when you need to ensure that specific groups, such as response teams, receive notifications regardless of filter criteria.

Request

Endpoint

POST /v1/broadcasts

POST https://api.open-ews.org/v1/broadcasts

Parameters

{
  "data": {
    "type": "broadcast",
    "attributes": {
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3"
    },
    "relationships": {
      "beneficiary_groups": {
        "data": [
          {
            "type": "beneficiary_group",
            "id": 39
          }
        ]
      }
    }
  }
}

Name	Description
data[type] required	Must be `broadcast`
data[attributes][channel] required	Must be one of `voice`.
data[attributes][audio_url] required	A publicly available URL which contains the broadcast message.
data[attributes][status]	If supplied, must be `running`. This will create the broadcast and start it immediately.
data[attributes][metadata]	Set of key-value pairs that you can attach to the broadcast. This can be useful for storing additional information about the broadcast in a structured format.
data[attributes][beneficiary_filter][phone_number][$operator]	The phone number of the beneficiary.
data[attributes][beneficiary_filter][status][$operator]	Must be one of `active`, `disabled`.
data[attributes][beneficiary_filter][gender][$operator]	Must be one of `M` or `F`.
data[attributes][beneficiary_filter][disability_status][$operator]	Must be one of `normal`, `disabled`.
data[attributes][beneficiary_filter][date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
data[attributes][beneficiary_filter][iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][beneficiary_filter][iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
data[attributes][beneficiary_filter][created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
data[attributes][beneficiary_filter][address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
data[attributes][beneficiary_filter][address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][beneficiary_filter][address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][beneficiary_filter][address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][beneficiary_filter][address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][beneficiary_filter][address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][beneficiary_filter][address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)
data[relationships][beneficiary_groups][data.*.type]	Must be `beneficiary_group`
data[relationships][beneficiary_groups][data.*.id]	The unique ID of the beneficiary group

Response

location: https://api.open-ews.org/v1/broadcasts/60
201 Created

{
  "data": {
    "id": "60",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3",
      "metadata": {},
      "beneficiary_filter": {},
      "status": "pending",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": [
          {
            "id": "39",
            "type": "beneficiary_group"
          }
        ]
      }
    }
  }
}

Create broadcast for specific beneficiaries

You can create a broadcast for a specific set of beneficiaries using the phone number filter. This is especially useful when you want to quickly send a message to a known group—such as staff, partners, or a predefined list—without needing to assign them to a beneficiary group. It's also helpful for testing broadcasts in a live environment without affecting the full beneficiary population. The priority remains the same as standard broadcasts, ensuring consistent behavior while giving you more control over delivery.

Request

Endpoint

POST /v1/broadcasts

POST https://api.open-ews.org/v1/broadcasts

Parameters

{
  "data": {
    "type": "broadcast",
    "attributes": {
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3",
      "status": "running",
      "beneficiary_filter": {
        "phone_number": {
          "in": [
            "855972345785",
            "855972345786"
          ]
        }
      }
    }
  }
}

Name	Description
data[type] required	Must be `broadcast`
data[attributes][channel] required	Must be one of `voice`.
data[attributes][audio_url] required	A publicly available URL which contains the broadcast message.
data[attributes][status]	If supplied, must be `running`. This will create the broadcast and start it immediately.
data[attributes][metadata]	Set of key-value pairs that you can attach to the broadcast. This can be useful for storing additional information about the broadcast in a structured format.
data[attributes][beneficiary_filter][phone_number][$operator]	The phone number of the beneficiary.
data[attributes][beneficiary_filter][status][$operator]	Must be one of `active`, `disabled`.
data[attributes][beneficiary_filter][gender][$operator]	Must be one of `M` or `F`.
data[attributes][beneficiary_filter][disability_status][$operator]	Must be one of `normal`, `disabled`.
data[attributes][beneficiary_filter][date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
data[attributes][beneficiary_filter][iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][beneficiary_filter][iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
data[attributes][beneficiary_filter][created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
data[attributes][beneficiary_filter][address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
data[attributes][beneficiary_filter][address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][beneficiary_filter][address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][beneficiary_filter][address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][beneficiary_filter][address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][beneficiary_filter][address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][beneficiary_filter][address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)
data[relationships][beneficiary_groups][data.*.type]	Must be `beneficiary_group`
data[relationships][beneficiary_groups][data.*.id]	The unique ID of the beneficiary group

Response

location: https://api.open-ews.org/v1/broadcasts/61
201 Created

{
  "data": {
    "id": "61",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3",
      "metadata": {},
      "beneficiary_filter": {
        "phone_number": {
          "in": [
            "855972345785",
            "855972345786"
          ]
        }
      },
      "status": "queued",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": []
      }
    }
  }
}

Start a broadcast

Request

Endpoint

PATCH /v1/broadcasts/:id

PATCH https://api.open-ews.org/v1/broadcasts/62

Parameters

{
  "data": {
    "id": 62,
    "type": "broadcast",
    "attributes": {
      "status": "running"
    }
  }
}

Name	Description
data[id] required	The unique identifier of the broadcast.
data[type] required	Must be `broadcast`
data[attributes][audio_url]	A publicly available URL which contains the broadcast message. Can only be updated before the broadcast starts.
data[attributes][status]	Update the status of a broadcast. Must be one of `running`, `stopped`.
data[attributes][metadata]	Set of key-value pairs that you can attach to the broadcast. This can be useful for storing additional information about the broadcast in a structured format.
data[relationships][beneficiary_groups][data.*.type]	Must be `beneficiary_group`
data[relationships][beneficiary_groups][data.*.id]	The unique ID of the beneficiary group
data[attributes][beneficiary_filter][phone_number][$operator]	The phone number of the beneficiary.
data[attributes][beneficiary_filter][status][$operator]	Must be one of `active`, `disabled`.
data[attributes][beneficiary_filter][gender][$operator]	Must be one of `M` or `F`.
data[attributes][beneficiary_filter][disability_status][$operator]	Must be one of `normal`, `disabled`.
data[attributes][beneficiary_filter][date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
data[attributes][beneficiary_filter][iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][beneficiary_filter][iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
data[attributes][beneficiary_filter][created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
data[attributes][beneficiary_filter][address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
data[attributes][beneficiary_filter][address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][beneficiary_filter][address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][beneficiary_filter][address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][beneficiary_filter][address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][beneficiary_filter][address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][beneficiary_filter][address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": {
    "id": "62",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": "https://www.example.com/test.mp3",
      "metadata": {},
      "beneficiary_filter": {
        "gender": {
          "eq": "F"
        }
      },
      "status": "queued",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": []
      }
    }
  }
}

Stop a broadcast

Request

Endpoint

PATCH /v1/broadcasts/:id

PATCH https://api.open-ews.org/v1/broadcasts/63

Parameters

{
  "data": {
    "id": 63,
    "type": "broadcast",
    "attributes": {
      "status": "stopped"
    }
  }
}

Name	Description
data[id] required	The unique identifier of the broadcast.
data[type] required	Must be `broadcast`
data[attributes][audio_url]	A publicly available URL which contains the broadcast message. Can only be updated before the broadcast starts.
data[attributes][status]	Update the status of a broadcast. Must be one of `running`, `stopped`.
data[attributes][metadata]	Set of key-value pairs that you can attach to the broadcast. This can be useful for storing additional information about the broadcast in a structured format.
data[relationships][beneficiary_groups][data.*.type]	Must be `beneficiary_group`
data[relationships][beneficiary_groups][data.*.id]	The unique ID of the beneficiary group
data[attributes][beneficiary_filter][phone_number][$operator]	The phone number of the beneficiary.
data[attributes][beneficiary_filter][status][$operator]	Must be one of `active`, `disabled`.
data[attributes][beneficiary_filter][gender][$operator]	Must be one of `M` or `F`.
data[attributes][beneficiary_filter][disability_status][$operator]	Must be one of `normal`, `disabled`.
data[attributes][beneficiary_filter][date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
data[attributes][beneficiary_filter][iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][beneficiary_filter][iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
data[attributes][beneficiary_filter][created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
data[attributes][beneficiary_filter][address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
data[attributes][beneficiary_filter][address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][beneficiary_filter][address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][beneficiary_filter][address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][beneficiary_filter][address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][beneficiary_filter][address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][beneficiary_filter][address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": {
    "id": "63",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": null,
      "metadata": {},
      "beneficiary_filter": {
        "gender": {
          "eq": "M"
        }
      },
      "status": "stopped",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": []
      }
    }
  }
}

Update a broadcast

Request

Endpoint

PATCH /v1/broadcasts/:id

PATCH https://api.open-ews.org/v1/broadcasts/65

Parameters

{
  "data": {
    "id": 65,
    "type": "broadcast",
    "attributes": {
      "audio_url": "https://www.example.com/new.mp3",
      "beneficiary_filter": {
        "gender": {
          "eq": "F"
        }
      }
    },
    "relationships": {
      "beneficiary_groups": {
        "data": [
          {
            "type": "beneficiary_group",
            "id": 40
          }
        ]
      }
    }
  }
}

Name	Description
data[id] required	The unique identifier of the broadcast.
data[type] required	Must be `broadcast`
data[attributes][audio_url]	A publicly available URL which contains the broadcast message. Can only be updated before the broadcast starts.
data[attributes][status]	Update the status of a broadcast. Must be one of `running`, `stopped`.
data[attributes][metadata]	Set of key-value pairs that you can attach to the broadcast. This can be useful for storing additional information about the broadcast in a structured format.
data[relationships][beneficiary_groups][data.*.type]	Must be `beneficiary_group`
data[relationships][beneficiary_groups][data.*.id]	The unique ID of the beneficiary group
data[attributes][beneficiary_filter][phone_number][$operator]	The phone number of the beneficiary.
data[attributes][beneficiary_filter][status][$operator]	Must be one of `active`, `disabled`.
data[attributes][beneficiary_filter][gender][$operator]	Must be one of `M` or `F`.
data[attributes][beneficiary_filter][disability_status][$operator]	Must be one of `normal`, `disabled`.
data[attributes][beneficiary_filter][date_of_birth][$operator]	Date of birth in `YYYY-MM-DD` format.
data[attributes][beneficiary_filter][iso_language_code][$operator]	The ISO 639-2 alpha-3 language code of the beneficiary.
data[attributes][beneficiary_filter][iso_country_code][$operator]	The ISO 3166-1 country code of the beneficiary.
data[attributes][beneficiary_filter][created_at][$operator]	The ISO 8601 timestamp of when the beneficiary was created.
data[attributes][beneficiary_filter][address.iso_region_code][$operator]	The ISO 3166-2 region code of the address
data[attributes][beneficiary_filter][address.administrative_division_level_2_code][$operator]	The second-level administrative subdivision code of the address (e.g. district code)
data[attributes][beneficiary_filter][address.administrative_division_level_2_name][$operator]	The second-level administrative subdivision name of the address (e.g. district name)
data[attributes][beneficiary_filter][address.administrative_division_level_3_code][$operator]	The third-level administrative subdivision code of the address (e.g. commune code)
data[attributes][beneficiary_filter][address.administrative_division_level_3_name][$operator]	The third-level administrative subdivision name of the address (e.g. commune name)
data[attributes][beneficiary_filter][address.administrative_division_level_4_code][$operator]	The forth-level administrative subdivision code of the address (e.g. village code)
data[attributes][beneficiary_filter][address.administrative_division_level_4_name][$operator]	The forth-level administrative subdivision name of the address (e.g. village name)

Response


200 OK

{
  "data": {
    "id": "65",
    "type": "broadcast",
    "attributes": {
      "created_at": "2025-06-12T13:11:16Z",
      "updated_at": "2025-06-12T13:11:16Z",
      "channel": "voice",
      "audio_url": "https://www.example.com/new.mp3",
      "metadata": {},
      "beneficiary_filter": {
        "gender": {
          "eq": "F"
        }
      },
      "status": "pending",
      "error_code": null
    },
    "relationships": {
      "beneficiary_groups": {
        "data": [
          {
            "id": "40",
            "type": "beneficiary_group"
          }
        ]
      }
    }
  }
}

Download a broadcast's audio file

Request

Endpoint

GET /v1/broadcasts/:broadcast_id/audio_file

GET https://api.open-ews.org/v1/broadcasts/67/audio_file

Parameters

None known.

Response

location: https://api.open-ews.org/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJwMWtqZmR5aW8xcHh3ZndmYTF4cHBhemp2NDZlIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRlc3QubXAzXCI7IGZpbGVuYW1lKj1VVEYtOCcndGVzdC5tcDMiLCJjb250ZW50X3R5cGUiOiJhdWRpby9tcGVnIiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI1LTA2LTEyVDEzOjE2OjE3LjA0NFoiLCJwdXIiOiJibG9iX2tleSJ9fQ==--0825cc1f7a134faabf24252b142b241deb066b5a/test.mp3
302 Found

Events

The Events API provides a structured way to track and respond to significant changes within the OpenEWS system. An event represents something that has occurred—such as the creation, update, or deletion of a key resource like a beneficiary or broadcast. Events are generated in real time as the system state changes, enabling external services to monitor and react to important activity. This allows for powerful integrations, audit trails, automation, and synchronization across connected systems.

Typical use cases include:

Triggering notifications when new beneficiaries are registered
Syncing deletions or updates with third-party databases
Logging significant system activity for compliance or analytics

Each event includes metadata such as the event type and timestamp.

The Events API currently supports the following event types:

beneficiary.created
beneficiary.deleted

List all events

Request

Endpoint

GET /v1/events

GET https://api.open-ews.org/v1/events

Parameters

Name	Description
filter[type][$operator]	The event type. Must be one of `beneficiary.created`, `beneficiary.deleted`.
filter[created_at][$operator]	The ISO 8601 timestamp of the event.

Response


200 OK

{
  "data": [
    {
      "id": "5",
      "type": "event",
      "attributes": {
        "created_at": "2025-06-12T13:11:17Z",
        "updated_at": "2025-06-12T13:11:17Z",
        "type": "beneficiary.created",
        "details": {
          "data": {
            "id": "116",
            "type": "beneficiary"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/events?page%5Bbefore%5D=5",
    "next": null
  }
}

Filter events

Request

Endpoint

GET /v1/events

GET https://api.open-ews.org/v1/events?filter[type][eq]=beneficiary.deleted&amp;filter[created_at][gt]=2025-06-12+13%3A10%3A18+UTC

Parameters

{
  "filter": {
    "type": {
      "eq": "beneficiary.deleted"
    },
    "created_at": {
      "gt": "2025-06-12 13:10:18 UTC"
    }
  }
}

Name	Description
filter[type][$operator]	The event type. Must be one of `beneficiary.created`, `beneficiary.deleted`.
filter[created_at][$operator]	The ISO 8601 timestamp of the event.

Response


200 OK

{
  "data": [
    {
      "id": "7",
      "type": "event",
      "attributes": {
        "created_at": "2025-06-12T13:11:17Z",
        "updated_at": "2025-06-12T13:11:17Z",
        "type": "beneficiary.deleted",
        "details": {
          "data": {
            "id": "118",
            "type": "beneficiary"
          }
        }
      }
    }
  ],
  "links": {
    "prev": "https://api.open-ews.org/v1/events?filter%5Bcreated_at%5D%5Bgt%5D=2025-06-12+13%3A10%3A18+UTC&filter%5Btype%5D%5Beq%5D=beneficiary.deleted&page%5Bbefore%5D=7",
    "next": null
  }
}

Fetch an event

Request

Endpoint

GET /v1/events/:id

GET https://api.open-ews.org/v1/events/10

Parameters

None known.

Response


200 OK

{
  "data": {
    "id": "10",
    "type": "event",
    "attributes": {
      "created_at": "2025-06-12T13:11:17Z",
      "updated_at": "2025-06-12T13:11:17Z",
      "type": "beneficiary.created",
      "details": {
        "data": {
          "id": "121",
          "type": "beneficiary"
        }
      }
    }
  }
}

Fetch event stats

This example filters events by the type beneficiary.deleted and restricts the results to a specific time range. The returned data is grouped by event type

Request

Endpoint

GET /v1/events/stats

GET https://api.open-ews.org/v1/events/stats?filter[type][eq]=beneficiary.deleted&amp;filter[created_at][between][]=2025-06-08T13%3A11%3A17Z&amp;filter[created_at][between][]=2025-06-11T13%3A11%3A17Z&amp;group_by[]=type

Parameters

{
  "filter": {
    "type": {
      "eq": "beneficiary.deleted"
    },
    "created_at": {
      "between": [
        "2025-06-08T13:11:17Z",
        "2025-06-11T13:11:17Z"
      ]
    }
  },
  "group_by": [
    "type"
  ]
}

Name	Description
filter[type]	The event type. Must be one of `beneficiary.created`, `beneficiary.deleted`.
filter[created_at]	The ISO 8601 timestamp of the event.
group_by required	An array of fields to group by. Supported fields: `type`.

Response


200 OK

{
  "data": [
    {
      "id": "1f67722db66f4a7f4351f024c1176083884303da6d2e172a29e980fcf42d52ec",
      "type": "stat",
      "attributes": {
        "result": {
          "type": "beneficiary.deleted",
          "value": 2
        }
      }
    }
  ]
}