General

Welcome

The Relay API provides REST endpoints to manage all communication aspects of your communities:

Community management
Channel management
Notice creation
Distribution
Webhooks
..and much more!

Endpoint

Production: https://relay-api.d6.co.za

Versioning

The URL will contain a version number with ‘v’ prefix (E.g v1, v2) at the beginning of the query. E.g: https://relay-api.d6.co.za/api/business/v1/communities

Authentication


## Get Access Token (Client Credentials)
curl -X "POST" "https://id.zipalong.tech/connect/token" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "client_id={CLIENT_ID}" \
     --data-urlencode "client_secret={CLIENT_SECRET}" \
     --data-urlencode "scope=relay.business.full_access relay_uploads.upload"

{
  "access_token": "REDACTED", # The access token
  "expires_in": 604800,
  "token_type": "Bearer",
  "scope": "relay.business.full_access relay_uploads.upload"
}

Relay uses the d6 Identity Service (OAuth) for authentication and access to your server resources. All API requests require an access token which can be retrived using the Client Credentials grant type:

Access Token URL: https://id.zipalong.tech/connect/token
Client ID: Provided to you
Client Secret: Provided to you
Scopes: relay.business.full_access and/or relay.business.read_only and/or relay_uploads.upload

All API requests must be made over HTTPS. Requests made over plain HTTP will fail and may risk exposing your key.

Status Codes

Relay uses status codes that adhere to the HTTP/1.1 standard (RFC 7231):

Code	Name	Description
200	OK	The request has succeeded.
201	Created	Resource has been created.
202	Accepted	The request has been accepted for processing, but the processing has not been completed.
204	No Content	Resource has been deleted.
400	Bad Request	The request was invalid. E.g. No access token provided, an invalid UUID, or the request could not be completed.
401	Unauthorized	The access token is invalid or has expired.
403	Forbidden	The server understood the request, but is refusing it or the access is not allowed. E.g. The access token does not have the required scope.
404	Not Found	The resource was not found.
422	Unprocessable Entity	The server understood the request, but was unable to process the contained instructions. Normally due to missing or malformed parameters (validation errors).
429	Too Many Requests	Rate limits have been reached, please slow down your requests.
500	Internal Server Error	Internal server error which has been logged and being attended to. Please try again later.
503	Service Unavailable	API is down for maintenance. Please try again later.

Rate Limiting

Please be aware that should you exceed these limits you will receive a 429 (Too Many Requests) error:

60 requests every 1 minute per unique IP address

Every request will return X-RateLimit-Limit and X-RateLimit-Remaining in the headers to manage your throttling if necessary.

Date and Time

The date & time format used by the API is ISO 8601 UTC compliant:

Format: {YYYY-mm-dd}T{HH:mm:ss}Z
Example: 1994-11-05T13:15:30Z.

Errors & Bad Requests

{
  "message": "The error message goes here."
}

Errors or bad requests caught by the API will always return a JSON object with a message key. The value will always be a string.

Paginated Lists

{
  "data": [
    {
      "id": 1,
      "name": "Object 1",
    },
    {
      "id": 2,
      "name": "Object 2",
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 2,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/communities?page=2"
    }
  }
}

Many different requests in the Relay API provide the ability to paginate results. All paginated results follow the same response structure:

data array which contains the objects
pagination object which provides details about the pagination
- total property which provides the total amount of objects sans pagination
- count property which provides the amount of objects for the current page
- per_page property which provides the amount of objects currently being requested per page
- current_page property which provides the current page of the request taking into account the per_page and count
- total_pages property which provides the total amount of pages
- links object which provides useful URLs to navigate pages
  - next Full URL to the next page (Ommitted if no next page)
  - previous Full URL to the previous page (Ommitted if no previous page)

Expanding Relationships

curl "https://relay-api.d6.co.za/api/business/v1/channels/{id}?expand=community" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json"


{
  "id": 1,
  "community_id": 1,
  "name": "Channel Name",
  "created_at": "2020-09-22T08:29:00Z",
  "updated_at": "2020-09-22T08:29:00Z",

  "community": {
    "id": 1,
    "name": "Community Name",
    "created_at": "2020-09-22T08:29:00Z",
    "updated_at": "2020-09-22T08:29:00Z"
  }
}

Certain resources may reference other resources via their unique id. E.g: A channel belongs to a community.

Instead of making 2 requests to fetch a channel and then the community it belongs to, we can simply request the channel with an expand parameter/argument of 'community'. The response will then include the community as well.

All resources that have expandable relationships are documented in the requests found below.

Dedicated File Upload Endpoint

We provide an endpoint for you to upload, download and view files. This will avoid you having to to construct multipart form data requests. Instead, file id parameters can be provided in your JSON.

curl  -X "POST" "https://relay-uploads.d6.co.za/api/upload/v1/files" \
      -H "Authorization: Bearer {ACCESS_TOKEN}" \
      -H "Accept: application/json" \
      -H 'Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__' \
      -F "file=" \
      -F "metadata=\"{\\\"test\\\":\\\"data\\\"}\""

{
  "id": "95605ad2-d1f8-46ce-841c-ba42884903e8",
  "expires_at": "2022-01-24T09:12:11Z"
}

Request

POST https://relay-uploads.d6.co.za/api/upload/v1/files

Arguments (JSON)

Parameter	Type	Description
file _Optional	file	The file you would like to upload. Both the `file` and `url` parameters cannot be populated at the same time.
url _Optional	string	The url to the file you would like to upload.
metadata _Optional	string	The file's metadata.
expires_at _Optional	date	The file expiry date.
sandbox _Optional	boolean	Whether to fake uploading the file.

Returns

An object with an id and expires_at attributes with status code 200 (OK).

Communities

Communities represent businesses, clubs or schools. All data is segregated by community including notices & members.

Create a Community

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: multipart/form-data; charset=utf-8; boundary=__X_D6_BOUNDARY__' \
     -F "name=Community Name" \
     -F "type=school" \
     -F "email=contact@example.org" \
     -F "website=https://www.example.org" \
     -F "address=14 John Doe Street, Lynnwood, Pretoria" \
     -F "tier_id={TIER_ID}" \
     -F "image=" \
     -F "cover_image=" \
     -F "default_country_calling_code=27"

{
    "id": "92f6ff6e-dbee-4408-a736-6a8d43ccaf3f",
    "status": "active",
    "status_at": "2021-12-23T20:53:58Z", // When status was last changed
    "type": "school",
    "source": "manual",
    "invite_only": false,
    "locale": "en",
    "name": "Community Name",
    "short_name": null,
    "email": "contact@example.org",
    "phone_number": null,
    "website": "https:\/\/www.example.org",
    "address": "14 John Doe Street, Lynnwood, Pretoria",
    "image": "https:\/\/cdnrly.d6.co.za\/cm\/92f6ff6e-dbee-4408-a736-6a8d43ccaf3f\/60509b9f16f02\/20210316_b8a449891590bde01b7c79b7913269fe.jpg",
    "image_blurhash": "USMaR]?bj[M{~q-;j[j[_3ofWBM{ofWBofof",
    "image_width": 600,
    "image_height": 600,
    "cover_image": "https:\/\/cdnrly.d6.co.za\/cm\/92f6ff6e-dbee-4408-a736-6a8d43ccaf3f\/60657e3c9b039\/20210401_6347b9d342342a91dffe01f4281ba765.jpg",
    "cover_image_blurhash": "LeODIK-Vbbo}~qj[aej]57XSi_a0",
    "cover_image_width": 1067,
    "cover_image_height": 600,
    "email_cover_image": "https:\/\/cdnrly-staging.d6.co.za\/cm\/952f0b30-1dab-4ec1-a955-cd6c183fe09d\/62737b10ed1e1\/20220505_a64b18138a2a10fe90a5c4934f3a6aef.jpg",
    "d6_unique_zoho_reference": null,
    "account_contact_name": "John Doe",
    "account_contact_phone_number": null,
    "account_contact_email": null,
    "account_contact_notes": null,
    "app_accessible": true,
    "portal_accessible": true,
    "internal_stats_collection_enabled": false,
    "timezone": "UTC",
    "app_download_url": "https:\/\/www.d6.co.za",
    "ads_legacy_mobile_keyword": null,
    "ads_legacy_desktop_keyword": null,
    "default_country_calling_code": 27,
    "default_portal_notice_distribution_relationship": "default",
    "default_app_notice_distribution_relationship": "default",
    "default_portal_notice_platform_distribution_grouping": "app_email_sms",
    "default_app_notice_platform_distribution_grouping": "app_email_sms",
    "inactivity_reminder_emails_enabled": true,
    "default_currency_iso_4217": null,
    "portal_primarily_used": false,
    "allow_portal_locked_person_channel_updates": false,
    "legacy_d6_connect_id": null,
    "close_at": null,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "is_internal_community": false,
    "internal_community_description": null,
    "is_review_community": false,
    "hidden_notice_components": [],
    "new_comms_experience": false
}

Creates a new community.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities

Arguments (JSON)

Parameter	Type	Description
name _Required	string	The name of the community. Max length of 255 characters.
type _Required	string	Available types: 'school', 'club', 'business', 'other', 'unknown'.
tier_id _Required	string	The identifier (UUID) of the tier to create the community's plan from. These IDs will be provided to you.
short_name _Optional	string	A short name for the community. Max length of 10 characters.
status _Optional	string	The status of the community. Available types: 'active', 'closed'. Defaults to 'active'.
email _Optional	string	The email address of the community. Must be a valid email address. Max length of 255 characters.
phone_number _Optional	string	The phone number of the community. Max length of 255 characters.
website _Optional	string	The website of the community. Must be a valid URL. Max length of 255 characters.
address _Optional	string	The physical address of the community. Max length of 255 characters.
image _Optional	file	The logo of the community. Used in email headers and within the apps. Supported Formats: jpg, png, gif, heic, heif Max file size of 10MB.
cover_image _Optional	file	The cover image of the community. Used in email headers and within the apps. Supported Formats: jpg, png, gif, heic, heif Max file size of 10MB.
apps _Optional	array	Array of objects of apps this community should be attached to, each with a required `id` (App ID, provided to you) and an optional `visible` boolean.
app_ids _Optional	array	Array of App IDs this community should be attached to. These IDs will be provided to you. Kept for backwards compatibility; prefer `apps`.
region_ids _Optional	array	Array of Region IDs this community should be attached to. These IDs will be provided to you.
locale _Optional	string	The locale code (E.g en) of the community. Gets used for deciding the language to use throughout the service such as emails. Defaults to 'en'.
d6_unique_zoho_reference _Optional	string	Internal usage. Must be unique across communities. Max length of 255 characters.
account_contact_name _Optional	string	The name of the account contact. Max length of 255 characters.
account_contact_phone_number _Optional	string	The phone number for this account's contact. Must be a valid mobile number.
account_contact_email _Optional	string	The email address for this account's contact. Must be a valid email address. Max length of 255 characters.
account_contact_notes _Optional	string	Additional notes for this account. This field can be used for malformed `account_contact_phone_number` and `account_contact_email` details.
timezone _Optional	string	The community's timezone. Must be a valid timezone identifier (E.g `Africa/Johannesburg`). The default timezone is `UTC`.
app_download_url _Optional	string	The url this app can be downloaded from. Must be a valid URL. Max length of 255 characters.
default_country_calling_code _Optional	integer	A default country calling code used in member phone number validation and selection.
hidden_notice_components _Optional	array	List of notice components to NOT display when composing via Portal or apps. Used to avoid usage of specific components.

Returns

The newly created community object with status code 201 (Created).

Retrieve a Community

curl "https://relay-api.d6.co.za/api/business/v1/communities/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific community.

Request

GET https://relay-api.d6.co.za/api/business/v1/communities/{id}

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Query Parameters

Parameter	Description
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `apps`, `regions`, `plan`.

Returns

The community object with status code 200 (OK).

Update a Community

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "name": "Updated Name"
         }'

{
  "id": "92f6ff6e-dbee-4408-a736-6a8d43ccaf3f",
  "name": "Updated Name",
  ...
  "created_at": "2021-03-16T11:50:55Z",
  "updated_at": "2021-04-01T10:03:08Z"
}

Updates a specific community. Only specified arguments will be changed, omitted arguments will remain unchanged.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}

Note: This endpoint uses POST rather than PUT so that multipart/form-data (E.g image uploads) is supported.

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
name _Optional	string	The name of the community. Max length of 255 characters.
type _Optional	string	Available types: 'school', 'club', 'business', 'other', 'unknown'.
tier_id _Optional	string	The identifier (UUID) of the tier to move the community's plan to. These IDs will be provided to you.
short_name _Optional	string	A short name for the community. Max length of 10 characters.
status _Optional	string	The status of the community. Available types: 'active', 'closed'.
email _Optional	string	The email address of the community. Must be a valid email address. Max length of 255 characters.
phone_number _Optional	string	The phone number of the community. Max length of 255 characters.
website _Optional	string	The website of the community. Must be a valid URL. Max length of 255 characters.
address _Optional	string	The physical address of the community. Max length of 255 characters.
image _Optional	file	The logo of the community. Used in email headers and within the apps. Supported Formats: jpg, png, gif, heic, heif Max file size of 10MB.
cover_image _Optional	file	The cover image of the community. Used in email headers and within the apps. Supported Formats: jpg, png, gif, heic, heif Max file size of 10MB.
region_ids _Optional	array	Array of Region IDs this community should be attached to. These IDs will be provided to you. *Hint:* Previously submitted `region_ids` must be present in this array. If not they will be detached from the community.
locale _Optional	string	The locale code (E.g en) of the community. Gets used for deciding the language to use throughout the service such as emails. Defaults to 'en'.
d6_unique_zoho_reference _Optional	string	Internal usage. Must be unique across communities. Max length of 255 characters.
account_contact_name _Optional	string	The name of the account contact. Max length of 255 characters.
account_contact_phone_number _Optional	string	The phone number for this account's contact. Must be a valid mobile number.
account_contact_email _Optional	string	The email address for this account's contact. Must be a valid email address. Max length of 255 characters.
account_contact_notes _Optional	string	Additional notes for this account. This field can be used for malformed `account_contact_phone_number` and `account_contact_email` details.
timezone _Optional	string	The community's timezone. Must be a valid timezone identifier (E.g `Africa/Johannesburg`). The default timezone is `UTC`.
app_download_url _Optional	string	The url this app can be downloaded from. Must be a valid URL. Max length of 255 characters.
default_country_calling_code _Optional	integer	A default country calling code used in member phone number validation and selection.
hidden_notice_components _Optional	array	List of notice components to NOT display when composing via Portal or apps. Used to avoid usage of specific components.

Returns

The updated community object with status code 200 (OK).

Delete a Community

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/communities/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "92f6ff6e-dbee-4408-a736-6a8d43ccaf3f",
  "deleted": true
}

Deletes a specific community permanently. All data related to the community (notices, members etc.) will also be deleted.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/communities/{id}

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An object with an id and deleted attributes with status code 200 (OK).

List Communities

curl "https://relay-api.d6.co.za/api/business/v1/communities?page=1&per_page=20&sort=-name,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "92f6ff6e-dbee-4408-a736-6a8d43ccaf3f",
      "name": "Community Name 2",
      ...
      "created_at": "2017-09-29T09:53:21Z",
      "updated_at": "2017-09-29T09:53:21Z"
    },
    {
      "id": "12f6ff6e-dbee-4408-a736-6a8d43ccaf3d",
      "name": "Community Name",
      ...
      "created_at": "2017-09-22T08:29:00Z",
      "updated_at": "2017-09-22T08:29:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/communities?page=2"
    }
  }
}

Returns a paginated list of all communities sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/communities

Note: For situations where the query parameters are too long, a POST endpoint is also available that accepts the parameters in a JSON object: POST https://relay-api.d6.co.za/api/business/v1/communities/list

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of communities to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the communities by (ascending). Defaults to `-updated_at`. Sortable Properties: `name`, `type`, `status`, `status_at`, `source`, `email`, `phone_number`, `website`, `address`, `timezone`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `name` descending then by `created_at` ascending: `?sort=-name,created_at`.
search _Optional	Case insensitive string to search and filter communities by name.
ids _Optional	Comma separated string of `community` IDs to filter.
region_ids _Optional	Comma separated string of `region` IDs to filter.
source _Optional	Filter communities by source. Available sources: 'manual', 'zoho'.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `apps`, `regions`, `plan`.

Returns

A data array of community objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Suspend App Access

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/suspend-app" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Suspend app access for a specific community. Users will stop seeing the community and its content across all apps this community is attached to.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/suspend-app

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Resume App Access

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/resume-app" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Resume app access for a specific community.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/resume-app

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Suspend Portal Access

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/suspend-portal" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Suspend portal access for a specific community. Users will not be able to perform any actions on the community management portal.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/suspend-portal

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Resume Portal Access

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/resume-portal" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Resume portal access for a specific community.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/resume-portal

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Schedule Closure of Community

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/schedule-close" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json"
     -d '{
          "close_at": "2021-11-02T13:26:30+00:00"
        }'

{
  "success": true
}

Schedule the closure of a specific community for a provided date.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/schedule-close

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
close_at _Required	string	Future date in ISO 8601 format on when to close the community.

Returns

An success object with status code 200 (OK).

Remove Any Scheduled Closure of a Community

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/remove-scheduled-close" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Removes any scheduled closure of a specific community.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/remove-scheduled-close

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Lock Community Objects

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/lock" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Creates a lock on all existing persons, community users, events, and channels which prevents portal system users from altering anything on the locked objects.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/lock

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Unlock Community Objects

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/communities/{id}/unlock" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "success": true
}

Removes any locks on all existing persons, community users, events, and channels.

Request

POST https://relay-api.d6.co.za/api/business/v1/communities/{id}/unlock

URL Parameters

Parameter	Description
id	The identifier of the `community` which was returned upon creation.

Returns

An success object with status code 200 (OK).

Community Users (Portal Users)

Community users refer to the community's management portal users.

Invite a Community User

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/community-users/invites" \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "email": "example@d6.co.za",
            "community_roles": [
                "community_owner"
            ],
            "community_id": "bb60bd90-6973-3934-b165-5850c357ac68",
            "is_locked": true
        }'

{
  "id": "95829603-7d29-4eb4-a806-dc7a71976981",
  "community_id": "bb60bd90-6973-3934-b165-5850c357ac68",
  "email": "example@d6.co.za",
  "community_roles": [
    "community_owner"
  ],
  "channel_roles": [],
  "created_at": "2022-02-03T09:35:51Z",
  "updated_at": "2022-02-03T09:35:51Z",
  "is_locked": true
}

Invite a user to a specific community's management portal.

Request

POST https://relay-api.d6.co.za/api/business/v1/community-users/invites

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this community user belongs to.
email _Required	string	The user's email address. Must be a valid email address. The invitation to access the specified community management portal will be sent to this email address.
community_roles _Optional	Array	An array of `community` roles to be assigned to this community user. Available Community Roles: `community_owner`, `community_admin`, `all_channels_contributor`, `all_channels_moderator`.
channel_roles _Optional	Array	An array of objects, each containing a `channel_id` (required, must belong to the community) and a `roles` array of `channel` roles to be assigned to the community user for that channel. Available Channel Roles: `channel_moderator`, `channel_contributor`.
is_locked _Optional	Boolean	Whether to lock the related `community_user` object so that it can only be modified or deleted via the API. Defaults to `true`.

Returns

The newly created community_invite object with status code 201 (Created).

List Community Users Invites

curl "https://relay-api.d6.co.za/api/business/v1/community-users/invites" \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json'

{
  "data": [
    {
      "id": "9560dbe2-9f44-408f-9f27-8a43f1934c6f",
      "community_id": "92f6fc67-fa40-4477-9709-5a93ad33067e",
      "email": "example@d6.co.za",
      "community_roles": [
        "community_owner"
      ],
      "channel_roles": [],
      "created_at": "2022-01-17T15:13:04Z",
      "updated_at": "2022-01-17T15:13:04Z",
      "is_locked": true
    },
    {
      "id": "95470ce7-47ce-4f63-9015-36c703419f81",
      "community_id": "951006d7-922a-4481-85f0-d91085255450",
      "email": "example2@d6.co.za",
      "community_roles": [
        "community_owner"
      ],
      "channel_roles": [],
      "created_at": "2022-01-04T19:18:37Z",
      "updated_at": "2022-01-04T19:18:37Z",
      "is_locked": true
    }
  ],
  "pagination": {
    "total": 2,
    "count": 2,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": []
  }
}

Returns a paginated list of all community users invites.

Note: Once an invite has been accepted by the user it will no longer be in this list.

Request

GET https://relay-api.d6.co.za/api/business/v1/community-users/invites

Query Parameters

Parameter	Description
sort _Optional	Comma separated string of properties to sort the community invites by (ascending). Defaults to `-updated_at`. Sortable Properties: `community_id`, `email`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending.
search _Optional	Case insensitive string to search and filter community invites by email (partial match).
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of community invites to return per page. Defaults to `15`. Maximum of `100`.
ids _Optional	Comma separated string of `community_invite` IDs to filter.
community_ids _Optional	Comma separated string of `community` IDs to filter.

Returns

A data array of community_invite objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Delete a Community User Invite

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/community-users/invites/{id}" \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {ACCESS_TOKEN}'

{
  "id": "95829603-7d29-4eb4-a806-dc7a71976981",
  "deleted": true
}

Delete a specific community user invite permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/community-users/invites/{id}

URL Parameters

Parameter	Description
id	The identifier of the `community_invite` which was returned upon creation.

Returns

An object with an id and deleted attributes with status code 200 (OK).

Delete Multiple Community Users Invites

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/community-users/invites" \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
          "invite_ids": [
            "958ac459-efe7-4824-9ad4-e523eb89ee7d",
            "958ac431-bac1-48b9-9938-26e10a6d9836"
          ]
        }'

{
  "ids": [
    "958ac431-bac1-48b9-9938-26e10a6d9836",
    "958ac459-efe7-4824-9ad4-e523eb89ee7d"
  ],
  "deleted": true
}

Delete multiple community user invites permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/community-users/invites

Arguments (JSON)

Parameter	Type	Description
invite_ids _Required	Array	An array of `invite` IDs to be deleted.

Returns

An object with an ids and deleted attributes with status code 200 (OK).

Resend a Community User Invite

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/community-users/invites/{id}/resend" \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {ACCESS_TOKEN}'

{
  "success": true
}

Resend a community invite to a user.

Request

POST https://relay-api.d6.co.za/api/business/v1/community-users/invites/{id}/resend

URL Parameters

Parameter	Description
id	The identifier of the `community_invite` which was returned upon creation.

Returns

A success object with status code 200 (OK).

Update a Community User

curl    -X "PUT" "https://relay-api.d6.co.za/api/business/v1/community-users/{id}" \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Accept-Language: ' \
        -H 'Content-Type: application/json; charset=utf-8' \
        -d $'{
            "channel_roles": [
                {
                    "roles": [
                        "channel_contributor",
                        "channel_moderator"
                    ],
                    "channel_id": "9580e5bf-9766-417a-9545-116656cb10e9"
                }
            ],
            "community_roles": [
                "community_owner"
            ],
            "community_id": "bb60bd90-6973-3934-b165-5850c357ac68",
            "is_locked": true
        }'

{
  "id": "85890309-27fc-4e4b-85b6-130fbe329c20",
  "email": "example@d6.co.za",
  "phone_number": "+27662449755",
  "first_name": "Eulalia",
  "last_name": "Gleichner",
  "communities": [
    {
      "id": "bb60bd90-6973-3934-b165-5850c357ac68",
      "community_roles": [
        "community_owner"
      ],
      "channel_roles": {
        "9580e5bf-9766-417a-9545-116656cb10e9": [
          "channel_contributor",
          "channel_moderator"
        ]
      },
      "is_locked": true
    }
  ],
  "created_at": "2022-01-26T09:10:56Z",
  "updated_at": "2022-01-26T09:10:58Z"
}

Updates a specific community user. Only specified arguments will be changed, omitted arguments will remain unchanged.

Request

PUT https://relay-api.d6.co.za/api/business/v1/community-users/{id}

URL Parameters

Parameter	Description
id	The identifier of the `community_user` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the `community` that this community user belongs to.
community_roles _Optional	Array	An array of community roles to be assigned to this community user. Available Community Roles:`community_owner`, `community_admin`, `all_channels_contributor`, `all_channels_moderator`.
channel_roles _Optional	Array	An array of objects, each containing a `channel_id` (required, must belong to the community) and a `roles` array (required) of roles to be assigned to the `community_user` for that channel. Available Channel Roles: `channel_moderator`, `channel_contributor`.
is_locked _Optional	Boolean	Whether to lock the related `community_user` object so that it can only be modified or deleted via the API. Defaults to `true`.
first_name _Optional	string	The user's first name. Max length of 255 characters.
last_name _Optional	string	The user's last name. Max length of 255 characters.
email _Optional	string	The user's email address. Must be a valid email address. Max length of 255 characters.
phone_number _Optional	string	The user's phone number. Max length of 20 characters.

Returns

The updated community_user object with status code 200 (OK).

Detach a Community User

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/community-users/{id}/detach" \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "4b82bb39-4a1c-3c9d-a882-8a291b8715a8"
        }'

{
  "success": true   
}

Detach a user from a specific community. The user will no longer have access to the community management portal.

Request

POST https://relay-api.d6.co.za/api/business/v1/community-users/{id}/detach

URL Parameters

Parameter	Description
id	The identifier of the `community_user` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the `community` this user will be detached from.

Returns

A success object with status code 200 (OK).

Detach Multiple Community Users

curl    -X "POST" "https://relay-api.d6.co.za/api/business/v1/community-users/detach" \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json; charset=utf-8' \
        -d $'{
            "user_ids": [
                "d32fed5e-6d7b-3c30-bda9-f05e373b5405",
                "a9c08733-2258-35e3-8143-3e3745b42631"
            ],
            "community_id": "bb60bd90-6973-3934-b165-5850c357ac68"
        }'

{
  "success": true   
}

Detach multiple users from a specific community. The users will no longer have access to the community management portal.

Request

POST https://relay-api.d6.co.za/api/business/v1/community-users/detach

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the `community` that users will be detached from.
user_ids _Required	Array	An array of `user` IDs to be detached from the specified community.

Returns

A success object with status code 200 (OK).

List Community Users

curl "https://relay-api.d6.co.za/api/business/v1/community-users?sort=first_name&page=1&per_page=3" \
     -H 'Authorization: Bearer {ACCESS_TOKEN}' \
     -H 'Accept: application/json'

{
  "data": [
    {
      "id": "1284ef82-7f44-3439-a10c-088fd4b6eef2",
      "email": "example@d6.co.za",
      "phone_number": "+6326943009478",
      "first_name": "Glennie",
      "last_name": "Pagac",
      "communities": [
        {
          "id": "bb60bd90-6973-3934-b165-5850c357ac68",
          "community_roles": [],
          "channel_roles": {
            "5c95eebc-3d22-3b7d-8c71-3cf153b307e1": [
              "channel_moderator"
            ]
          },
          "is_locked": true
        }
      ],
      "created_at": "2022-01-26T09:10:58Z",
      "updated_at": "2022-01-26T09:10:58Z"
    }
  ],
  "pagination": {
    "total": 1,
    "count": 1,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": []
  }
}

Returns a paginated list of all community users sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/community-users

Query Parameters

Parameter	Description
sort _Optional	Comma separated string of properties to sort the community users by (ascending). Defaults to `-updated_at`. Sortable Properties: `first_name`, `last_name`, `email`, `phone_number`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending.
search _Optional	Case insensitive string to search and filter community users by `first_name` or `last_name`.
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of community users to return per page. Defaults to `15`. Maximum of `100`.
ids _Optional	Comma separated string of `community_user` IDs to filter.
community_ids _Optional	Comma separated string of `community` IDs to filter.
community_roles _Optional	Comma separated string of `community_roles` to filter. Available Community Roles: `community_owner`, `community_admin`, `all_channels_contributor`, `all_channels_moderator`.
channel_roles _Optional	Comma separated string of `channel_roles` to filter. Available Channel Roles: `channel_moderator`, `channel_contributor`.

Returns

A data array of community_users objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Contacts

Contacts are visible within the app as your typical "phone book" contacts. All contacts are visible to any user who is part of the community. Contacts can be used to share general contact information of a community.

Example: Creating a Mrs van Zyl - School Secretary contact with email and phone_number which users in the app will be able to save to their device phone book.

Contacts are accessible within the app in the "Contact Community" section located in the side menu.

Create a Contact

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/contacts" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "first_name": "Merike",
            "last_name": "van Zyl",
            "prefix": "Mrs",
            "title": "Secretary",
            "birthday": "24-07-1990",
            "org": "St Paulus Primary School",
            "facebook_url": "https://www.facebook.com/theurl",
            "twitter_url": "https://twitter.com/theurl",
            "note": "The secretary to the Principal.",
            "work_emails": [
                "m.vanzyl@example.org"
            ],
            "home_emails": [],
            "work_telephones": [],
            "home_telephones": [
                "+2751511151"
            ]
        }'

{
    "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
    "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
    "first_name": "Merike",
    "last_name": "van Zyl",
    "prefix": "Mrs",
    "title": "Secretary",
    "middle_name": null,
    "birthday": "1990-07-24",
    "org": "St Paulus Primary School",
    "facebook_url": "https://www.facebook.com/theurl",
    "twitter_url": "https://twitter.com/theurl",
    "note": "The secretary to the Principal.",
    "work_emails": [
        "m.vanzyl@example.org"
    ],
    "home_emails": [],
    "work_telephones": [],
    "home_telephones": [
        "+2751511151"
    ],
    "vcard": "BEGIN:VCARD\r\nVERSION:3.0\r\n...\r\nEND:VCARD",
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z"
}

Creates a new contact.

Request

POST https://relay-api.d6.co.za/api/business/v1/contacts

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this contact belongs to.
prefix _Optional	string	The prefix of the contact. Max length of 255 characters.
first_name _Optional	string	The first name of the contact. Max length of 255 characters.
middle_name _Optional	string	The middle name of the contact. Max length of 255 characters.
last_name _Optional	string	The last name of the contact. Max length of 255 characters.
title _Optional	string	The title/role of the contact (E.g Secretary). Max length of 255 characters.
birthday _Optional	string	The birthday of the contact (Format: DD-MM-YYYY).
org _Optional	string	The organisation name the contact belongs to. Max length of 255 characters.
work_emails _Optional	array	Array of work email addresses. Each must be a valid email address.
home_emails _Optional	array	Array of home/personal email addresses. Each must be a valid email address.
home_telephones _Optional	array	Array of home/personal telephone number strings preferably in E.164 format. Max length of 255 characters each.
work_telephones _Optional	array	Array of work telephone number strings preferably in E.164 format. Max length of 255 characters each.
note _Optional	string	Notes/description of the contact. Max length of 255 characters.
facebook_url _Optional	string	URL to the contact's Facebook page. Must be a valid URL. Max length of 255 characters.
twitter_url _Optional	string	URL to the contact's Twitter page. Must be a valid URL. Max length of 255 characters.

Returns

The newly created contact object with status code 201 (Created).

Retrieve a Contact

curl "https://relay-api.d6.co.za/api/business/v1/contacts/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific contact.

Request

GET https://relay-api.d6.co.za/api/business/v1/contacts/{id}

URL Parameters

Parameter	Description
id	The identifier of the `contact` which was returned upon creation.

Returns

The contact object with status code 200 (OK).

Update a Contact

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/contacts/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "first_name": "Updated Name"
         }'

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "first_name": "Updated First Name",
  ...
  "created_at": "2021-03-16T11:50:55Z",
  "updated_at": "2021-04-01T10:03:08Z"
}

Updates a specific contact. Only specified arguments will be changed, ommitted arguments will remain unchanged.

Request

PUT https://relay-api.d6.co.za/api/business/v1/contacts/{id}

URL Parameters

Parameter	Description
id	The identifier of the `contact` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
prefix _Optional	string	The prefix of the contact. Max length of 255 characters.
first_name _Optional	string	The first name of the contact. Max length of 255 characters.
middle_name _Optional	string	The middle name of the contact. Max length of 255 characters.
last_name _Optional	string	The last name of the contact. Max length of 255 characters.
title _Optional	string	The title/role of the contact (E.g Secretary). Max length of 255 characters.
birthday _Optional	string	The birthday of the contact (Format: DD-MM-YYYY).
org _Optional	string	The organisation name the contact belongs to. Max length of 255 characters.
work_emails _Optional	array	Array of work email addresses. Each must be a valid email address.
home_emails _Optional	array	Array of home/personal email addresses. Each must be a valid email address.
home_telephones _Optional	array	Array of home/personal telephone number strings preferably in E.164 format. Max length of 255 characters each.
work_telephones _Optional	array	Array of work telephone number strings preferably in E.164 format. Max length of 255 characters each.
note _Optional	string	Notes/description of the contact. Max length of 255 characters.
facebook_url _Optional	string	URL to the contact's Facebook page. Must be a valid URL. Max length of 255 characters.
twitter_url _Optional	string	URL to the contact's Twitter page. Must be a valid URL. Max length of 255 characters.

Returns

The updated contact object with status code 200 (OK).

Delete a Contact

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/contacts/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "deleted": true
}

Deletes a specific contact permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/contacts/{id}

URL Parameters

Parameter	Description
id	The identifier of the `contact` which was returned upon creation.

Returns

An object with an id and deleted attributes with status code 200 (OK).

List Contacts

curl "https://relay-api.d6.co.za/api/business/v1/contacts?page=1&per_page=20&sort=-first_name,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
      "first_name": "Merike",
      ...
      "created_at": "2017-09-29T09:53:21Z",
      "updated_at": "2017-09-29T09:53:21Z"
    },
    {
      "id": "12f6ff6e-dbee-4408-a736-6a8d43ccaf3d",
      "first_name": "Alan",
      ...
      "created_at": "2017-09-22T08:29:00Z",
      "updated_at": "2017-09-22T08:29:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/contacts?page=2"
    }
  }
}

Returns a paginated list of all contacts sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/contacts

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of contacts to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the contacts by (ascending). Defaults to `-updated_at`. Sortable Properties: `community_id`, `prefix`, `first_name`, `middle_name`, `last_name`, `title`, `birthday`, `org`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `first_name` descending then by `created_at` ascending: `?sort=-first_name,created_at`.
search _Optional	Case insensitive string to search and filter contacts by `first_name` or `last_name`.
ids _Optional	Comma separated string of `contact` IDs to filter.
community_ids _Optional	Comma separated string of `community` IDs to filter.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`.

Returns

A data array of contact objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this tag belongs to.
name _Required	string	The name of the tag. Max length of 255 characters.

Parameter	Description
id	The identifier of the `tag` which was returned upon creation.

Parameter	Description
id	The identifier of the `tag` which was returned upon creation.

Parameter	Type	Description
name _Optional	string	The name of the tag. Max length of 255 characters.

Parameter	Description
id	The identifier of the `tag` which was returned upon creation.

Persons

Persons refer to members of a specific community or in other words, the community communication contact list.

Create a Person

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/persons" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "first_name": "Leroy",
            "last_name": "Jenkins",
            "unique_identifier" : "AB-122",
            "email" : "person@example.org",
            "phone_number": "+2761124222"
        }'

{
    "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
    "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
    "is_public_follower": false,
    "unique_identifier": "AB-122",
    "first_name": "Leroy",
    "last_name": "Jenkins",
    "email": "person@example.org",
    "phone_number": "+2761124222",
    "id_number": null,
    "app_last_seen_at": null,
    "last_seen_at_chatbot_whatsapp": null,
    "last_seen_at_chatbot_app": null,
    "last_seen_at_chatbot": null,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "is_locked": false,
    "debtor_reference": null
}

Creates a new person.

Request

POST https://relay-api.d6.co.za/api/business/v1/persons

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this person belongs to.
first_name _Optional	string	The first name of the person. Max length of 255 characters.
last_name _Optional	string	The last name of the person. Max length of 255 characters.
unique_identifier _Optional	string	A unique identifier for your internal use (E.g Employee number). Must be unique within the community. Max length of 255 characters.
email _Optional	string	The email address of the person. Must be a valid email address. Max length of 255 characters.
phone_number _Optional	string	The mobile phone number of the person. Format: E.164 (E.g +27000000000)
id_number _Optional	string	The ID or passport number of the person. Max length of 255 characters.
debtor_reference _Optional	string	The debtor reference of the person. Max length of 255 characters.
channel_ids _Optional	array	Array of `channel` IDs this person should be attached to on creation. Channels must belong to the community.
tag_ids _Optional	array	Array of `tag` IDs this person should be attached to on creation. Tags must belong to the community.
update_app_channel_subscriptions _Optional	boolean	Whether any app users linked to this person should have any channels subscribed on their behalf depending on the `channel_ids` and `tag_ids` attributes. Defaults to `true`.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether app users should receive a notification about these channel subscriptions that happened on their behalf. Defaults to `false`.
update_app_community_subscriptions _Optional	boolean	Whether any app users linked to this person should be automatically subscribed to the community, if not already subscribed. Defaults to `true`.
notify_community_subscription_changes_via_app _Optional	boolean	If `update_app_community_subscriptions` is `true`, whether app users should receive a notification about the community subscription that happened on their behalf. Defaults to `true`.
parent_person_ids _Optional	array	An array of parent Person IDs this person should be attached to. Persons must belong to the community.
child_person_ids _Optional	array	An array of child Person IDs this person should be attached to. Persons must belong to the community.
is_locked _Optional	boolean	Whether to lock this person so that only the API can make further changes to the object. Defaults to `false`.
expand _Optional	string	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `tags`, `parents`, `children`.

Returns

The newly created person object with status code 201 (Created).

Retrieve a Person

curl "https://relay-api.d6.co.za/api/business/v1/persons/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific person.

Request

GET https://relay-api.d6.co.za/api/business/v1/persons/{id}

URL Parameters

Parameter	Description
id	The identifier of the `person` which was returned upon creation.

Query Parameters

Parameter	Description
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `tags`, `parents`, `children`.

Returns

The person object with status code 200 (OK).

Update a Person

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/persons/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "email": "updated@example.org"
         }'

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  ...
  "email": "updated@example.org",
  ...
  "created_at": "2021-03-16T11:50:55Z",
  "updated_at": "2021-04-01T10:03:08Z"
}

Updates a specific person. Only specified arguments will be changed, ommitted arguments will remain unchanged.

Request

PUT https://relay-api.d6.co.za/api/business/v1/persons/{id}

URL Parameters

Parameter	Description
id	The identifier of the `person` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
first_name _Optional	string	The first name of the person. Max length of 255 characters.
last_name _Optional	string	The last name of the person. Max length of 255 characters.
unique_identifier _Optional	string	A unique identifier for your internal use (E.g Employee number). Must be unique within the community. Max length of 255 characters.
email _Optional	string	The email address of the person. Must be a valid email address. Max length of 255 characters. Nullable.
phone_number _Optional	string	The mobile phone number of the person. Format: E.164 (E.g +27000000000). Nullable.
id_number _Optional	string	The ID or passport number of the person. Max length of 255 characters.
debtor_reference _Optional	string	The debtor reference of the person. Max length of 255 characters.
channel_ids _Optional	array	Array of `channel` IDs this person should be attached to. Replaces the existing channel attachments. Channels must belong to the person's community.
tag_ids _Optional	array	Array of `tag` IDs this person should be attached to. Replaces the existing tag attachments. Tags must belong to the person's community.
update_app_channel_subscriptions _Optional	boolean	Whether any app users linked to this person should have any channels subscribed/unsubscribed on their behalf depending on the `channel_ids` and `tag_ids` attributes. Defaults to `true`.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether app users should receive a notification about these channel subscriptions/unsubscriptions that happened on their behalf. Defaults to `false`.
update_app_community_subscriptions _Optional	boolean	Whether any app users linked to this person should be automatically subscribed to the community, if not already subscribed. Defaults to `false`.
notify_community_subscription_changes_via_app _Optional	boolean	If `update_app_community_subscriptions` is `true`, whether app users should receive a notification about the community subscription that happened on their behalf. Defaults to `true`.
parent_person_ids _Optional	array	An array of parent Person IDs this person should be attached to.
child_person_ids _Optional	array	An array of child Person IDs this person should be attached to.
is_locked _Optional	boolean	Whether to lock this person so that only the API can make further changes to the object.
convert_to_public_follower_instead_of_detaching _Optional	boolean	When channels are removed via `channel_ids`, whether the person should be converted to a public follower of those channels instead of being detached. Defaults to `false` for third-party clients and `true` for first-party clients.
expand _Optional	string	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `tags`, `parents`, `children`.

Returns

The updated person object with status code 200 (OK).

Delete a Person

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/persons/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "deleted": true
}

Deletes a specific person permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/persons/{id}

URL Parameters

Parameter	Description
id	The identifier of the `person` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
notify_community_subscription_changes_via_app _Optional	boolean	Whether app users linked to this person should receive a notification about the community unsubscription that happened on their behalf. Defaults to `false`.

Returns

An object with an id and deleted attributes with status code 200 (OK).

Delete Multiple Persons

curl  -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/persons" \
      -H "Authorization: Bearer {ACCESS_TOKEN}" \
      -H "Accept: application/json" \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
            "person_ids": [
              "9a2bb989-f1be-3a46-8748-2667a166074b",
              "67a2ea04-decb-3f66-b619-cfde929669c0"
            ]
          }'

{
  "ids": [
    "9a2bb989-f1be-3a46-8748-2667a166074b",
    "67a2ea04-decb-3f66-b619-cfde929669c0"
  ],
  "deleted": true
}

Deletes specified persons permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/persons

Arguments (JSON)

Parameter	Type	Description
person_ids _Required	array	Array of `person` IDs that were returned upon creation.
notify_community_subscription_changes_via_app _Optional	boolean	Whether app users linked to these persons should receive a notification about the community unsubscription that happened on their behalf. Defaults to value of `notify_subscription_changes_via_app` (which defaults to `false`).

Returns

An object with an ids and deleted attributes with status code 200 (OK).

List Persons

curl "https://relay-api.d6.co.za/api/business/v1/persons?page=1&per_page=20&sort=-first_name,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
      "first_name": "Zelda",
      ...
      "created_at": "2017-09-29T09:53:21Z",
      "updated_at": "2017-09-29T09:53:21Z"
    },
    {
      "id": "12f6ff6e-dbee-4408-a736-6a8d43ccaf3d",
      "first_name": "Nuah",
      ...
      "created_at": "2017-09-22T08:29:00Z",
      "updated_at": "2017-09-22T08:29:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/persons?page=2"
    }
  }
}

Returns a paginated list of all persons sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/persons

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of persons to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the persons by (ascending). Defaults to `-updated_at`. Sortable Properties: `first_name`, `last_name`, `unique_identifier`, `email`, `phone_number`, `id_number`, `app_last_seen_at`, `last_invited_app_at`, `last_seen_at_chatbot_whatsapp`, `last_seen_at_chatbot_app`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `first_name` descending then by `created_at` ascending: `?sort=-first_name,created_at`.
search _Optional	Case insensitive string to search and filter persons by. Matches (partially) against first name, last name, full name, phone number, email, ID number, unique identifier and debtor reference, or exactly against the person ID. Multiple search terms can be comma separated.
ids _Optional	Comma separated string of `person` IDs to filter.
community_ids _Optional	Comma separated string of `community` IDs to filter.
channel_ids _Optional	Comma separated string of `channel` IDs to filter.
tag_ids _Optional	Comma separated string of `tag` IDs to filter.
unique_identifier _Optional	Filter persons by an exact `unique_identifier` match.
debtor_reference _Optional	Filter persons by an exact `debtor_reference` match.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `tags`, `parents`, `children`.

Returns

A data array of person objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Channels

Channels can be used to group specific persons for repeatable targeting. If configured so, they can also be joined by your community members via the app.

Example: Creating a Grade 1 Parents channel which only parents of Grade 1 children can join or a General Announcements channel which anyone can join.

A channel can also be expired once it has served its purpose. An expired channel keeps all of its content visible to its existing members in the app, but can no longer be joined, left, or targeted with new notices, and is hidden from the app's channel lists. Expiry is reversible; deleting remains the only way to remove a channel and its content. Set expires_at to have a channel expire automatically on a date, or use the expire endpoint to do it immediately.

Create a Channel

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/channels" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "name": "Grade 1 Parents",
            "invite_only": true,
            "is_hidden" : false,
            "is_default" : false,
            "can_leave": false
        }'

{
    "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
    "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
    "name": "Grade 1 Parents",
    "type": null,
    "invite_only": true,
    "is_hidden": false,
    "is_default": false,
    "can_leave": false,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "is_locked": false,
    "is_visible_for_selection": true,
    "integrations_d6_plus_channel": false,
    "integrations_d6_plus_channel_id": null,
    "is_temporary": false,
    "is_expired": false,
    "expired_at": null,
    "expires_at": null,
    "expiry_reason": null,
    "expired_by_rollover_id": null
}

Creates a new channel.

Request

POST https://relay-api.d6.co.za/api/business/v1/channels

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier (UUID) of the community that this channel belongs to.
name _Required	string	The name of the channel. Max length of 255 characters.
type _Optional	string	The category of the channel. Available types: `grade`, `register_class`, `subject`, `house`, `boarding`, `campus`, `division`, `department`, `sports_team`, `cultural_group`, `supporters`, `staff`, `committee`, `parent_group`, `learner_group`, `announcement`, `ad_hoc`, `unspecified`.
invite_only _Optional	boolean	Whether the channel can be joined by users themselves (E.g via app). Note: tag_ids and person_ids taken into account.
is_hidden _Optional	boolean	Whether the channel is visible to app users.
is_default _Optional	boolean	When a user subscribes to the community, the channel will automatically be added to the user's subscribed channels. Example: The `General Announcements` channel must be attached to all new users. Note: `tag_ids` and `person_ids` taken into account.
can_leave _Optional	boolean	Whether users can unsubscribe/leave the channel themselves (E.g via app).
tag_ids _Optional	array	Array of Tag IDs this channel should be associated with. This then controls who can join/subscribe to the channel. Example: Attaching a `Parent` tag to the channel will only allow community members with the `Parent` tag to join/subscribe to the channel.
person_ids _Optional	array	Array of `Person` IDs this channel should be associated with. This then controls who specifically can join the channel.
update_app_channel_subscriptions _Optional	boolean	Whether any app users that are associated to this channel (either via tag or directly attached via person_ids) should be subscribed/unsubscribed to the channel on their behalf. Defaults to `true`.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether app users should receive a notification about these channel subscriptions/unsubscriptions that happened on their behalf. Defaults to `false`.
is_locked _Optional	boolean	Whether to lock this channel so that only the API can make further changes to the object.
is_visible_for_selection _Optional	boolean	Whether the channel appears in selection lists. Defaults to `true` on create.
attach_all_persons_in_community _Optional	boolean	Immediately attach all `persons` in the community to the channel, regardless of `tag_ids`/`person_ids` rules. Defaults to `false`.
attach_persons_with_tag_ids _Optional	array	Array of Tag IDs. Immediately attach all `persons` with any of these tags to the channel.
attach_persons_with_ids _Optional	array	Array of `Person` IDs to immediately attach to the channel.
expires_at _Optional	string	ISO 8601 date and time at which this channel should automatically expire. A channel with an `expires_at` is a temporary channel. Send `null` to cancel a pending expiry. Omitting this argument leaves any existing value unchanged. A date in the past is accepted and will be actioned within a minute.

Returns

The newly created channel object with status code 201 (Created).

Retrieve a Channel

curl "https://relay-api.d6.co.za/api/business/v1/channels/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific channel.

Request

GET https://relay-api.d6.co.za/api/business/v1/channels/{id}

URL Parameters

Parameter	Description
id	The identifier of the `channel` which was returned upon creation.

Query Parameters

Parameter	Description
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `tags`, `persons`.

Returns

The channel object with status code 200 (OK).

Update a Channel

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/channels/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "name": "Updated Name"
         }'

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "name": "Updated Name",
  ...
  "created_at": "2021-03-16T11:50:55Z",
  "updated_at": "2021-04-01T10:03:08Z"
}

Updates a specific channel. Only specified arguments will be changed, ommitted arguments will remain unchanged.

Request

PUT https://relay-api.d6.co.za/api/business/v1/channels/{id}

URL Parameters

Parameter	Description
id	The identifier of the `channel` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
name _Optional	string	The name of the channel. Max length of 255 characters.
type _Optional	string	The category of the channel. Available types: `grade`, `register_class`, `subject`, `house`, `boarding`, `campus`, `division`, `department`, `sports_team`, `cultural_group`, `supporters`, `staff`, `committee`, `parent_group`, `learner_group`, `announcement`, `ad_hoc`, `unspecified`.
invite_only _Optional	boolean	Whether the channel can be joined by users themselves (E.g via app). Note: tag_ids and person_ids taken into account.
is_hidden _Optional	boolean	Whether the channel is visible to app users.
is_default _Optional	boolean	When a user subscribes to the community, the channel will automatically be added to the user's subscribed channels. Example: The `General Announcements` channel must be attached to all new users. Note: `tag_ids` and `person_ids` taken into account.
can_leave _Optional	boolean	Whether users can unsubscribe/leave the channel themselves (E.g via app).
tag_ids _Optional	array	Array of Tag IDs this channel should be associated with. This then controls who can join/subscribe to the channel. Example: Attaching a `Parent` tag to the channel will only allow community members with the `Parent` tag to join/subscribe to the channel.
person_ids _Optional	array	Array of `Person` IDs this channel should be associated with. This then controls who specifically can join the channel.
update_app_channel_subscriptions _Optional	boolean	Whether any app users that are associated to this channel (either via tag or directly attached via person_ids) should be subscribed/unsubscribed to the channel on their behalf. Defaults to `true`.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether app users should receive a notification about these channel subscriptions/unsubscriptions that happened on their behalf. Defaults to `false`.
is_locked _Optional	boolean	Whether to lock this channel so that only the API can make further changes to the object.
is_visible_for_selection _Optional	boolean	Whether the channel appears in selection lists.
expires_at _Optional	string	ISO 8601 date and time at which this channel should automatically expire. A channel with an `expires_at` is a temporary channel. Send `null` to cancel a pending expiry. Omitting this argument leaves any existing value unchanged. A date in the past is accepted and will be actioned within a minute.

Returns

The updated channel object with status code 200 (OK).

Expire a Channel

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/channels/{id}/expire" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "expired": true,
  "expired_at": "2026-09-04T08:12:44Z"
}

Expires a specific channel immediately.

The channel keeps all of its content: its notices, events and payments stay visible to its existing members in the app, and its members and their app subscriptions are left untouched. What changes is that the channel is hidden from the app's channel lists, can no longer be joined or left, its membership can no longer be modified, and it can no longer be targeted by new notices. If the channel had chat enabled, the conversation becomes read-only history.

Sets expiry_reason to manual. To have a channel expire automatically on a date instead, set expires_at on create or update.

Request

POST https://relay-api.d6.co.za/api/business/v1/channels/{id}/expire

URL Parameters

Parameter	Description
id	The identifier of the `channel` which was returned upon creation.

Returns

An object with id, expired and expired_at attributes with status code 200 (OK).

Attempting to expire a channel that is already expired returns 400 (Bad Request) with error code 1220.

Because a client is not a user, expired_by is not set for expiries performed through this API. The action is attributed to your client in the channel's audit trail instead.

Unexpire a Channel

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/channels/{id}/unexpire" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "expired": false,
  "expired_at": null
}

Removes the expiry from a specific channel, returning it to normal. Because expiry never removed the channel's members, it comes back with its membership intact.

Also clears expiry_reason. A pending expires_at that is already in the past is cleared too, so the channel is not immediately expired again; an expires_at still in the future is deliberately kept.

This endpoint is idempotent — calling it on a channel that is not expired returns 200 (OK) rather than an error.

Request

POST https://relay-api.d6.co.za/api/business/v1/channels/{id}/unexpire

URL Parameters

Parameter	Description
id	The identifier of the `channel` which was returned upon creation.

Returns

An object with id, expired and expired_at attributes with status code 200 (OK).

Delete a Channel

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/channels/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "deleted": true
}

Deletes a specific channel permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/channels/{id}

URL Parameters

Parameter	Description
id	The identifier of the `channel` which was returned upon creation.

Returns

An object with an id and deleted attributes with status code 200 (OK).

List Channels

curl "https://relay-api.d6.co.za/api/business/v1/channels?page=1&per_page=20&sort=-name,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
      "name": "Channel Name 2",
      ...
      "created_at": "2017-09-29T09:53:21Z",
      "updated_at": "2017-09-29T09:53:21Z"
    },
    {
      "id": "12f6ff6e-dbee-4408-a736-6a8d43ccaf3d",
      "name": "Channel Name",
      ...
      "created_at": "2017-09-22T08:29:00Z",
      "updated_at": "2017-09-22T08:29:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/channels?page=2"
    }
  }
}

Returns a paginated list of all channels sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/channels

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of channels to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the channels by (ascending). Defaults to `-updated_at`. Sortable Properties: `name`, `type`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `name` descending then by `created_at` ascending: `?sort=-name,created_at`.
search _Optional	Case insensitive string to search and filter channels by name.
ids _Optional	Comma separated string of `channel` IDs to filter.
community_ids _Optional	Comma separated string of `community` IDs to filter.
filter_by_type _Optional	Comma separated string of channel `type` values to filter by. Available types: `grade`, `register_class`, `subject`, `house`, `boarding`, `campus`, `division`, `department`, `sports_team`, `cultural_group`, `supporters`, `staff`, `committee`, `parent_group`, `learner_group`, `announcement`, `ad_hoc`, `unspecified`.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `tags`, `persons`.

Returns

A data array of channel objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Attach Persons to a Channel

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/channels/{id}/persons/attach" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "person_ids": ["22f6f48b-e219-4eec-b4ce-04cad170ffff", "12f6f48b-e219-4eec-b4ce-04cad170fff1"]
            "update_app_channel_subscriptions": true
            "notify_subscription_changes_via_app": true
        }'

{
    "success": true
}

Attaches specified persons to a channel.

Request

POST https://relay-api.d6.co.za/api/business/v1/channels/{id}/persons/attach

Arguments (JSON)

Parameter	Type	Description
person_ids _Required	array	Array of `Person` IDs to attach to this channel.
update_app_channel_subscriptions _Optional	boolean	Whether any app users should automatically be subscribed to this channel. Defaults to true.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether the user should be notified via push notification and in feed message. Defaults to `false`.

Returns

A success object with status code 200 (OK).

Detach Persons from a Channel

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/channels/{id}/persons/detach" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "person_ids": ["22f6f48b-e219-4eec-b4ce-04cad170ffff", "12f6f48b-e219-4eec-b4ce-04cad170fff1"]
            "notify_subscription_changes_via_app": true
        }'

{
    "success": true
}

Detaches specified persons from a channel.

Request

POST https://relay-api.d6.co.za/api/business/v1/channels/{id}/persons/detach

Arguments (JSON)

Parameter	Type	Description
person_ids _Required	array	Array of `Person` IDs to detach from this channel.
update_app_channel_subscriptions _Optional	boolean	Whether any app users should automatically be unsubscribed from this channel. Defaults to `true`.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether the user should be notified via push notification and in feed message. Defaults to `false`.

Returns

A success object with status code 200 (OK).

Notices

Notices (or messages) refer to any published communication within a community. Notices can be delivered over different platforms such as email, sms and via the app.

Notices are composed of different components which each serve different purposes. E.g Creating a notice with a text and you_tube_video component will appear as text and a video within the app.

Notices are created with a draft status by default and need to be published using a dedicated /publish endpoint.

Components

{
    "type": "text",
    "media_type": "plain", // Required. Can be plain, markdown, or html
    "text": "Plain text goes here",
}

{
    "type": "file",
    "file_id": "file_id_goes_here", // The file ID returned from Dedicated File Upload Endpoint
}

{
    "type": "image",
    "image_id": "image_id", // The file ID returned from Dedicated File Upload Endpoint
}

{
    "type": "web_frame",
    "url": "https://d6.co.za",
}

{
    "type": "contact",
    "first_name" : "Merike",
    "last_name" : "van Zyl",
    "title_or_role" : "Secretary",
    "description" : "This is a short description.",
    "website" : "https://www.example.org",
    "primary_phone_number" : "+2766121312",
    "secondary_phone_number" : "012 361 3402",
    "primary_email" : "merike@example.org",
    "secondary_email" : "merike.secondary@example.org",
    "birthday": "24-07-1990",
    "twitter_handle" : "@merikeexample",
    "facebook_url" : "https://www.facebook.com/marikeexample",
}

{
    "type"              : "event",
    "title"             : "Rugby U/12 Practice",
    "description"       : "This is a short description.",
    "address"           : "159 Gousblom Avenue, Lynnwood, Pretoria",
    "start_date"        : "2020-03-21T10:30:00+0200", // ISO 8601 with local timezone
    "end_date"          : "2020-03-21T12:30:00+0200", // ISO 8601 with local timezone
    "all_day"           : false,  // note that this will modify start + end_dates to the start and end of those days
    "add_calendar"      : false, // whether to add to calendars related to the notice channels + persons
    "remind_minutes"    : 0, // number of minutes before the event start_date time to send a reminder (note how all_day will adjust the start_date when setting this). Defaults to 0 (no reminder).
    "repeat"            : "NEVER", // event repeat options: NEVER, DAILY, WEEKLY, MONTHLY, ANNUALLY, WEEK_DAY, CUSTOM
    "recurrence_rules"  : ["RRULE:FREQ=DAILY", "EXDATE:20221011T142200Z"], // array of custom recurrence rule strings, use repeat = CUSTOM along with this
}


{
    "type": "response_text",
    "title": "What is your name?",
    "required": true
}

{
    "type": "response_boolean",
    "title": "Are you enjoying the weather today?",
    "required": true
}

{
    "type": "response_choice",
    "title": "Choose your favourite fruit:",
    "required": true,
    "single_selection": true,
    "options": [
        "Apple",
        "Orange",
        "Strawberry"
    ],
    "min": 1,   // Optional, one can now use min and max (deprecates `single_selection`) to control the minimum and maximum number of selections the user can make.
    "max": 1    // Optional, max cannot be greater than the number of choices.
}

{
    "type": "response_file",
    "title": "Please provide the signed PDF document:",
    "required": true
}

{
    "type": "response_image",
    "title": "Please provide a photo of your dog:",
    "required": true
}

{
    "type": "location",
    "latitude": "-25.5868815",
    "longitude": "28.322987",
    "address": "Plot 52, Buffelsdrift Conservancy, Buffelsdrift St, Pretoria, 0130"
}


{
    "type": "youtube_video",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" // Needs to be a publically available YouTube url
}

{
    "type": "payment",
    "payment_type": "fixed", // fixed, open, itemised or partial
    "title": "School Spring Walk Entry Fee",
    "amount_smallest_unit": 10000, // Amount in the currency's smallest unit (e.g. cents). Min 100, max 50000000. Required unless payment_type is open
    "currency_iso_4217": "ZAR",
    "item_quantity_limit": null, // If itemised, optional integer to set overall stock limit
}

{
    "type": "album",
    "name": "Album with 5 Images", <--- NULLABLE
    "medias": [ <--- MAX OF 1000
        {
            "image_id": "965fe019-a366-444b-87fc-77e08bb59470" // File ID returned by our dedicated file upload endpoint.
        },
        {
            "image_id": "965fe01a-e4c6-46f0-b23b-aeda2299cb2f"
        },
        {
            "image_id": "965fe01a-e4d4-49bf-b06a-677fafad0ba9"
        },
        {
            "image_id": "965fe01b-7580-4a0e-a0a3-c4012de60b64"
        },
        {
            "image_id": "965fe01b-72fc-4306-b1ac-742d3c3a2330"
        }
    ]
}

{
    "type": "url",
    "url": "https://www.d6.co.za", // Needs to be a publically available url
    "title": "d6.co.za",            // Nullable
    "description": "d6 Home page",  // Nullable
    "thumbnail_url": null           
}

The following components are currently available via the API:

Type	Description
`text`	Supported media types: `plain`, `markdown` or `html`. If HTML, supports the following tags: `<p>`, `<em>`, `<ins>`, `<del>`, `<strong>`, `<sup>`, `<sub>`, `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>`, `<blockquote>`, `<pre>`, `<ol>`, `<ul>`, `<li>`, `<a>`
`file`	Used for sharing specific files. Max 50MB. Most formats are supported.
`image`	Individual image to display. Max 50MB. Supported formats: `jpeg`, `png`, `gif`, `heic`, `heif`
`web_frame`	Akin to an iFrame, display an entire website within the notice. Temporarily disabled: requests containing a `web_frame` component are rejected with a validation error; use a `text` or `url` component with the URL instead.
`contact`	Display a contact within the notice that users can share/save.
`event`	Display an event within the notice that users can share/save.
`response_text`	Allows users to respond to the notice with any text.
`response_boolean`	Allows users to respond to boolean questions.
`response_choice`	Allows users to respond with either single or multiple choices.
`response_file`	Allows users to respond with a file.
`response_image`	Allows users to respond with an image.
`location`	Display a location within a notice. Users can view a map and can navigate to the location.
`youtube_video`	Display a video within the notice. Users can play the video.
`payment`	Displays a payment item. Users can pay with supported payment methods configured for the community of the notice.
`album`	Used for displaying multiple images. Max of 1000 images. Supported formats: jpeg, png, gif, heic, heif
`url`	Display an interactable link within a notice or resource.

Create a Notice

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/notices" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8"
            "channel_ids": [
                "32f6f48b-e219-4eec-b4ce-04cad170ffa9"
            ],
            "person_ids": [
                "aaf6f48b-e219-4eec-24ce-04cad17000a0",
            ],
            "title": "A Notice With Some Text and a Link",
            "components": [
                {
                    "type": "text",
                    "media_type": "html",
                    "text": "<p><strong>Hello everyone!</strong></p><p>This component supports basic HTML tags.</p>"
                },
                {
                    "type": "url",
                    "url": "https://d6.co.za"
                }
            ]
        }'

{
    "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
    "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
    "status": "draft",
    "status_at": "2021-03-16T11:50:55Z",
    "title": "A Notice With Some Text and a Link",
    "author": "Example Community",
    "target_everyone": false,
    "important": false,
    "answerable": false,
    "payable": false,
    "votable": false,
    "publish_platform_app": false,
    "publish_platform_email": false,
    "publish_platform_sms": false,
    "publish_platform_whatsapp": false,
    "publish_sandbox_app": false,
    "publish_sandbox_email": false,
    "publish_sandbox_sms": false,
    "publish_sandbox_whatsapp": false,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-03-16T11:50:55Z",
    "edited_at": null,
    "deadline_at": "2022-02-01T09:02:01Z",
    "has_hard_deadline": false
}

Creates a new notice.

Request

POST https://relay-api.d6.co.za/api/business/v1/notices

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this notice belongs to.
title _Required	string	The title of the notice. Max length of 255 characters.
target_everyone _Optional	boolean	Whether *everyone* in the community should be targeted. Omit `channel_ids`, `person_ids` when this is set to true.
channel_ids _Optional	array	Array of `channel` IDs this notice should target.
person_ids _Optional	array	Array of `person` IDs this notice should target.
components _Required	array	Array of component objects to build the notice with (min 1, max 100). Components are discussed in detail above.
important _Optional	boolean	Whether this is an important notice. This affects the way the notice is presented across the different platforms (E.g 'IMPORTANT' in email title and red looking notice cells/rows in the app).
deadline_at _Optional	string	Date and time representing the last moment at which responses and votes will be still be accepted from a member. ISO 8601 with local timezone. Nullable.
publish_relationship _Optional	string	Which linked persons should receive the notice. One of `default`, `root_only`, `children_only`, `parents_only`. Defaults to `default`.

Returns

The newly created notice object with status code 201 (Created).

Retrieve a Notice

curl "https://relay-api.d6.co.za/api/business/v1/notices/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific notice.

Request

GET https://relay-api.d6.co.za/api/business/v1/notices/{id}

URL Parameters

Parameter	Description
id	The identifier of the `notice` which was returned upon creation.

Query Parameters

Parameter	Description
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `components`.

Returns

The notice object with status code 200 (OK).

Retrieve Publish Breakdown

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/notices/{id}/publish/breakdown" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
            "strategy": "cheapest",
            "platforms": [
                "app",
                "email",
                "sms"
            ]
        }'

{
    "total": 12,
    "num_app": 10,
    "num_email": 2,
    "num_sms": 0,
    "num_whatsapp": 0,
    "num_unreachable": 0
}

Get the reachable count for a notice grouped by platform: app, email & sms. This allows you to see how a notice will reach everyone once published.

Request

POST https://relay-api.d6.co.za/api/business/v1/notices/{id}/publish/breakdown

URL Parameters

Parameter	Description
id	The identifier of the `notice` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
strategy _Required	string	Either `cheapest` or `send_all`. The `cheapest` strategy will try send notice to anyone with the app, if they don't have the app, then via email if they have an email address. Lastly, if they don't have an email on record, then via SMS if they have a phone number on record. The `send_all` strategy will send the notice across all platforms even if it means the end user will receive it across multiple platforms.
platforms _Optional	array	Array of platforms to target. Available platforms: `app`, `email`, `sms`.
relationship _Optional	string	One of `default`, `root_only`, `children_only`, `parents_only`. Defaults to the `publish_relationship` set on the notice.

Returns

The breakdown object with status code 200 (OK).

Update a Notice

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/notices/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "title": "Updated Title"
         }'

{
    "id": "96662f9c-974c-49c8-8315-f3de489f8ad7",
    "community_id": "95d372ec-5c85-46c3-a4de-3fe6058dbcaf",
    "status": "draft",
    "status_at": "2022-05-27T12:58:16Z",
    "title": "Updated Title",
    "author": "Example Community",
    "target_everyone": false,
    "important": false,
    "answerable": false,
    "payable": false,
    "votable": false,
    "publish_platform_app": false,
    "publish_platform_email": false,
    "publish_platform_sms": false,
    "publish_platform_whatsapp": false,
    "publish_sandbox_app": false,
    "publish_sandbox_email": false,
    "publish_sandbox_sms": false,
    "publish_sandbox_whatsapp": false,
    "created_at": "2022-05-27T12:58:16Z",
    "updated_at": "2022-05-27T12:59:00Z",
    "edited_at": null,
    "deadline_at": null,
    "has_hard_deadline": false
}

Updates a specific notice. Only specified arguments will be changed, omitted arguments will remain unchanged.

Request

PUT https://relay-api.d6.co.za/api/business/v1/notices/{id}

URL Parameters

Parameter	Description
id	The identifier of the `notice` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
title _Optional	string	The title of the notice. Max length of 255 characters.
components _Optional	array	Array of edited components to build the notice with (min 1, max 100).
target_everyone _Optional	boolean	Whether *everyone* in the community should be targeted. Omit `channel_ids`, `person_ids` when this is set to true.
channel_ids _Optional	array	Array of `channel` IDs this notice should target.
person_ids _Optional	array	Array of `person` IDs this notice should target.
important _Optional	boolean	Whether this is an important notice.
deadline_at _Optional	string	Date and time representing the last moment at which responses and votes will be still be accepted from a member. ISO 8601 with local timezone. Nullable.

Returns

The updated notice object with status code 200 (OK).

Third-party clients cannot update notices that are no longer in a draft or scheduled status; a 422 validation error is returned.

Publish Notice

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/notices/{id}/publish" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
            "strategy": "cheapest",
            "platforms": ["app"],
            "send_push_notification": true
        }'

{
    "success": true
}

Publish a specific notice. Once notices are published, they cannot be published again (a 422 validation error is returned). Publishing happens asynchronously; the notice status will move to publishing and then published.

Request

POST https://relay-api.d6.co.za/api/business/v1/notices/{id}/publish

URL Parameters

Parameter	Description
id	The identifier of the `notice` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
strategy _Required	string	Either `cheapest` or `send_all`. The `cheapest` strategy will try send notice to anyone with the app, if they don't have the app, then via email if they have an email address. Lastly, if they don't have an email on record, then via SMS if they have a phone number on record. The `send_all` strategy will send the notice across all platforms even if it means the end user will receive it across multiple platforms.
platforms _Optional	array	Array of platforms to target. Available platforms: `app`, `email`, `sms`.
send_push_notification _Optional	boolean	Whether app users should receive a push notification for this notice. Defaults to `false`.
relationship _Optional	string	One of `default`, `root_only`, `children_only`, `parents_only`. Defaults to the `publish_relationship` set on the notice.

Returns

Success object status code 200 (OK).

Archive a Notice

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/notices/{id}/archive" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
    "success": true
}

Archive a specific notice. This allows you to hide the notice from the app but not delete it permanently. Archived notices can still be queried via the /list endpoint.

Request

POST https://relay-api.d6.co.za/api/business/v1/notices/{id}/archive

URL Parameters

Parameter	Description
id	The identifier of the `notice` which was returned upon creation.

Returns

A success object with status code 200 (OK).

Unarchive a Notice

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/notices/{id}/unarchive" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
    "success": true
}

Unarchive a specific notice. This allows you to restore a notice to its previous status.

Request

POST https://relay-api.d6.co.za/api/business/v1/notices/{id}/unarchive

URL Parameters

Parameter	Description
id	The identifier of the `notice` which was returned upon creation.

Returns

A success object with status code 200 (OK).

List Notices

curl "https://relay-api.d6.co.za/api/business/v1/notices?page=1&per_page=20&sort=-title,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
      "title": "Notice Title 2",
      ...
      "created_at": "2017-09-29T09:53:21Z",
      "updated_at": "2017-09-29T09:53:21Z"
    },
    {
      "id": "12f6ff6e-dbee-4408-a736-6a8d43ccaf3d",
      "title": "Notice Title",
      ...
      "created_at": "2017-09-22T08:29:00Z",
      "updated_at": "2017-09-22T08:29:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/notices?page=2"
    }
  }
}

Returns a paginated list of all notices sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/notices

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of notices to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the notices by (ascending). Defaults to `-updated_at`. Sortable Properties: `title`, `num_read`, `status`, `status_at`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `title` descending then by `created_at` ascending: `?sort=-title,created_at`.
search _Optional	Case insensitive string to search and filter notices by title.
ids _Optional	Comma separated string of `notice` IDs to filter.
community_ids _Optional	Comma separated string of `community` IDs to filter.
channel_ids _Optional	Comma separated string of `channel` IDs to filter.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `components`.

Returns

A data array of notice objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

List Notice Recipients

curl "https://relay-api.d6.co.za/api/business/v1/notices/{id}/recipients?page=1&per_page=20&sort=-first_name,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "978caac3-c69b-4e91-bc24-a9123eab1c39",
      "notice_id": "96feae9d-bcb5-4bd0-bf7f-6350c44a5a62",
      "person_id": "978caab6-64c0-45e3-9ca1-4eae02621523",
      "unique_identifier": null,
      "first_name": "Some",
      "last_name": "Recipient",
      "email": "some.recipient@example.org",
      "phone_number": null,
      "app_push_sent_at": null,
      "app_push_delivered_at": null,
      "app_sent_at": "2022-10-20T22:16:01Z",
      "app_delivered_at": "2022-10-20T22:16:03Z",
      "app_opened_at": "2022-10-26T13:54:33Z",
      "email_sent_at": null,
      "email_delivered_at": null,
      "email_opened_at": null,
      "email_bounced_at": null,
      "email_rejected_at": null,
      "email_complained_at": null,
      "sms_sent_at": null,
      "sms_delivered_at": null,
      "sms_rejected_at": null,
      "sms_replied_at": null,
      "whatsapp_sent_at": null,
      "whatsapp_delivered_at": null,
      "whatsapp_opened_at": null,
      "whatsapp_rejected_at": null,
      "notice_paid_at": null,
      "notice_answered_at": null,
      "reminder_sent_at": null,
      "created_at": "2022-10-20T22:16:01Z",
      "updated_at": "2022-10-26T13:54:33Z"
    },
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/notices\/{id}\/recipients?page=2"
    }
  }
}

Returns a paginated list of all notice recipients sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/notices/{id}/recipients

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of recipients to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the recipients by (ascending). Defaults to `-updated_at`. Sortable Properties: `unique_identifier`, `first_name`, `last_name`, `email`, `phone_number`, `created_at`, `updated_at`, `app_push_sent_at`, `app_push_delivered_at`, `app_delivered_at`, `app_opened_at`, `email_sent_at`, `email_delivered_at`, `email_opened_at`, `email_bounced_at`, `email_rejected_at`, `email_complained_at`, `sms_sent_at`, `sms_delivered_at`, `sms_rejected_at`, `sms_replied_at`, `whatsapp_sent_at`, `whatsapp_delivered_at`, `whatsapp_opened_at`, `whatsapp_rejected_at`, `notice_paid_at`, `notice_answered_at`, `notice_voted_at`, `notice_last_submitted_at`, `notice_last_submitted_name`, `reminder_sent_at`, `parent_app_push_sent_at`, `parent_app_push_delivered_at`, `parent_app_sent_at`, `parent_app_delivered_at`, `parent_app_opened_at`, `parent_email_sent_at`, `parent_email_delivered_at`, `parent_email_opened_at`, `parent_email_bounced_at`, `parent_email_rejected_at`, `parent_email_complained_at`, `parent_sms_sent_at`, `parent_sms_delivered_at`, `parent_sms_rejected_at`, `parent_sms_replied_at`, `parent_whatsapp_sent_at`, `parent_whatsapp_delivered_at`, `parent_whatsapp_opened_at`, `parent_whatsapp_rejected_at`, `parent_notice_paid_at`, `parent_notice_answered_at`, `parent_notice_voted_at`, `child_app_push_sent_at`, `child_app_push_delivered_at`, `child_app_sent_at`, `child_app_delivered_at`, `child_app_opened_at`, `child_email_sent_at`, `child_email_delivered_at`, `child_email_opened_at`, `child_email_bounced_at`, `child_email_rejected_at`, `child_email_complained_at`, `child_sms_sent_at`, `child_sms_delivered_at`, `child_sms_rejected_at`, `child_sms_replied_at`, `child_whatsapp_sent_at`, `child_whatsapp_delivered_at`, `child_whatsapp_opened_at`, `child_whatsapp_rejected_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `first_name` descending then by `created_at` ascending: `?sort=-first_name,created_at`.
search _Optional	Case insensitive string to search and filter recipients by first or last names.
person_ids _Optional	Comma separated string of `person` IDs to filter recipients by.
only_paid_at _Optional	Boolean. If `true`, only returns recipients where `notice_paid_at` is not `null`.
only_answered_at _Optional	Boolean. If `true`, only returns recipients where `notice_answered_at` is not `null`.
statuses _Optional	Comma separated string of statuses to filter on: `app_push_sent_at`, `app_push_delivered_at`, `app_sent_at`, `app_delivered_at`, `app_opened_at`, `email_sent_at`, `email_delivered_at`, `email_opened_at`, `email_bounced_at`, `email_rejected_at`, `email_complained_at`, `sms_sent_at`, `sms_delivered_at`, `sms_rejected_at`, `sms_replied_at`, `whatsapp_sent_at`, `whatsapp_delivered_at`, `whatsapp_opened_at`, `whatsapp_rejected_at`, `notice_paid_at`, `notice_answered_at`, `notice_voted_at`, `reminder_sent_at`, `notice_last_submitted_at`, `parent_app_push_sent_at`, `parent_app_push_delivered_at`, `parent_app_sent_at`, `parent_app_delivered_at`, `parent_app_opened_at`, `parent_email_sent_at`, `parent_email_delivered_at`, `parent_email_opened_at`, `parent_email_bounced_at`, `parent_email_rejected_at`, `parent_email_complained_at`, `parent_sms_sent_at`, `parent_sms_delivered_at`, `parent_sms_rejected_at`, `parent_sms_replied_at`, `parent_whatsapp_sent_at`, `parent_whatsapp_delivered_at`, `parent_whatsapp_opened_at`, `parent_whatsapp_rejected_at`, `parent_notice_paid_at`, `parent_notice_answered_at`, `parent_notice_voted_at`, `child_app_push_sent_at`, `child_app_push_delivered_at`, `child_app_sent_at`, `child_app_delivered_at`, `child_app_opened_at`, `child_email_sent_at`, `child_email_delivered_at`, `child_email_opened_at`, `child_email_bounced_at`, `child_email_rejected_at`, `child_email_complained_at`, `child_sms_sent_at`, `child_sms_delivered_at`, `child_sms_rejected_at`, `child_sms_replied_at`, `child_whatsapp_sent_at`, `child_whatsapp_delivered_at`, `child_whatsapp_opened_at`, `child_whatsapp_rejected_at`. Any status can be prefixed with `not_` (e.g. `not_email_opened_at`) to filter recipients where that value is `null`. When multiple statuses are provided, recipients matching *any* of them are returned.

Returns

A data array of notice_recipient objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Analytics: Get Notice Recipient Status Counts

curl "https://relay-api.d6.co.za/api/business/v1/notices/{id}/analytics/recipient-status-counts" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "total_count": 1,
  "app_push_sent_count": 0,
  "app_push_delivered_count": 0,
  "app_sent_count": 1,
  "app_delivered_count": 0,
  "app_opened_count": 0,
  "email_sent_count": 0,
  "email_delivered_count": 0,
  "email_opened_count": 0,
  "email_bounced_count": 0,
  "email_rejected_count": 0,
  "email_complained_count": 0,
  "sms_sent_count": 0,
  "sms_delivered_count": 0,
  "sms_rejected_count": 0,
  "sms_replied_count": 0,
  "notice_paid_count": 0,
  "notice_answered_count": 0,
  "reminder_sent_count": 0,
  "parent_app_push_sent_count": 0,
  "parent_app_push_delivered_count": 0,
  "parent_app_sent_count": 0,
  "parent_app_delivered_count": 0,
  "parent_app_opened_count": 0,
  "parent_email_sent_count": 0,
  "parent_email_delivered_count": 0,
  "parent_email_opened_count": 0,
  "parent_email_bounced_count": 0,
  "parent_email_rejected_count": 0,
  "parent_email_complained_count": 0,
  "parent_sms_sent_count": 0,
  "parent_sms_delivered_count": 0,
  "parent_sms_rejected_count": 0,
  "parent_sms_replied_count": 0,
  "not_app_push_sent_count": 1,
  "not_app_push_delivered_count": 1,
  "not_app_sent_count": 0,
  "not_app_delivered_count": 1,
  "not_app_opened_count": 1,
  "not_email_sent_count": 1,
  "not_email_delivered_count": 1,
  "not_email_opened_count": 1,
  "not_email_bounced_count": 1,
  "not_email_rejected_count": 1,
  "not_email_complained_count": 1,
  "not_sms_sent_count": 1,
  "not_sms_delivered_count": 1,
  "not_sms_rejected_count": 1,
  "not_sms_replied_count": 1,
  "not_notice_paid_count": 1,
  "not_notice_answered_count": 1,
  "not_reminder_sent_count": 1,
  "not_parent_app_push_sent_count": 1,
  "not_parent_app_push_delivered_count": 1,
  "not_parent_app_sent_count": 1,
  "not_parent_app_delivered_count": 1,
  "not_parent_app_opened_count": 1,
  "not_parent_email_sent_count": 1,
  "not_parent_email_delivered_count": 1,
  "not_parent_email_opened_count": 1,
  "not_parent_email_bounced_count": 1,
  "not_parent_email_rejected_count": 1,
  "not_parent_email_complained_count": 1,
  "not_parent_sms_sent_count": 1,
  "not_parent_sms_delivered_count": 1,
  "not_parent_sms_rejected_count": 1,
  "not_parent_sms_replied_count": 1
}

Request

GET https://relay-api.d6.co.za/api/business/v1/notices/{id}/analytics/recipient-status-counts

Returns

Returns an object containing the counts of recipients for each status. Attributes prefixed with not_ are for statuses that are null. A total_count attribute is also provided which is the total number of recipients the notice is targeting. Attributes prefixed with parent_ denote that a parent person interacted with the notice on behalf of the recipient which is a child.

Analytics: Get Notice Engagement

curl "https://relay-api.d6.co.za/api/business/v1/notices/{id}/analytics/engagement" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "reachable_count": 0,
  "read_count": 0,
  "unread_count": 0,
  "read_percentage": 0,
  "unread_percentage": 100,
  "read_percentage_formatted": "0",
  "unread_percentage_formatted": "100"
}

Request

GET https://relay-api.d6.co.za/api/business/v1/notices/{id}/analytics/engagement

Returns

Returns an object containing the the total count of reachable recipients for a notice, additionally it will contain counts of recipients who have read and not read the notice. Raw float and formatted percentages are provided for convenience.

Analytics: Get Notice Distribution

curl "https://relay-api.d6.co.za/api/business/v1/notices/{id}/analytics/distribution" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "total_count": 0,
  "app_count": 0,
  "email_count": 0,
  "sms_count": 0,
  "app_percentage": 0,
  "email_percentage": 0,
  "sms_percentage": 0,
  "app_percentage_formatted": "0",
  "email_percentage_formatted": "0",
  "sms_percentage_formatted": "0"
}

Request

GET https://relay-api.d6.co.za/api/business/v1/notices/{id}/analytics/distribution

Returns

Returns an object containing the the total count of recipients the notice was sent to segregated by platform. Raw float and formatted percentages are provided for convenience.

Calendar Feeds

The Calendar Feeds API provides basic operations to link, fetch, update, unlink, delete, and forcefully re-sync a calendar feed.

While the d6 Calendar supports linking of Google, Microsoft, and iCal calendars feeds, only the latter is supported via this API for the time being.

Link iCal Calendar

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/link/ical" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
        "ical_url": "https://calendar.google.com/calendar/ical/qvbg5njr1a5idgi2pd6kug8ucg%40group.calendar.google.com/private-08d20d39da4bac833cb9d83483e01cb0/basic.ics",
        "name": "iCal test",
        "notify_synced_events": false,
        "is_sync_automatically": true,
        "target_everyone": false,
        "is_readonly": true,
        "channel_ids": [
          "9b2f439b-2f1d-4c4e-b869-cabe0c646fbf"
        ]
    }'

{
  "id": "9b34f2c6-187e-4336-b06f-df295f5197e0",
  "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
  "name": "iCal test",
  "display_name": "iCal test",
  "source": "9b34f2bf-ab99-4550-81e0-d2abc23d32ab",
  "synced_at": null,
  "sync_failed_at": null,
  "sync_failed_reason": null,
  "is_sync_automatically": true,
  "created_at": "2024-01-29T08:32:16Z",
  "updated_at": "2024-01-29T08:32:16Z",
  "events_count": 0,
  "is_default": false,
  "is_readonly": true,
  "target_everyone": false,
  "type": "ICAL_CALENDAR",
  "channels": [
    {
      "id": "9b2f439b-2f1d-4c4e-b869-cabe0c646fbf",
      "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
      "name": "Test Group",
      "invite_only": true,
      "is_hidden": false,
      "is_default": true,
      "can_leave": true,
      "created_at": "2024-01-26T12:43:20Z",
      "updated_at": "2024-01-26T12:43:20Z",
      "is_locked": false
    }
  ]
}

Links an iCal calendar feed to the community, applying default member targeting properties for synced events.

Request

POST https://relay-api.d6.co.za/api/business/v1/calendar-feeds/link/ical

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this calendar feed belongs to.
ical_url _Required	string	The URL to a public iCal (.ics) file. The file must be downloadable at the time of linking. If this URL is already linked to the community, the existing calendar feed is updated instead.
name _Required	string	A unique name for the calendar in context of the community.
notify_synced_events _Optional	bool	Whether to send scheduled reminder notifications to members for events which are newly synced for this calendar. Defaults to `false`.
is_sync_automatically _Optional	bool	Whether the calendar automatically re-syncs periodically (at present, once every 30 minutes). Defaults to `true`. Note that if `is_readonly` is not set, this could result in re-synced data overriding any changes made to an event from Portal or elsewhere.
target_everyone _Optional	bool	Whether the events synced for this calendar automatically target everyone, and at the same time, whether events that target everyone should go into this calendar; provided `is_readonly` is `false`. Defaults to `false`.
is_readonly _Optional	bool	This flag is optional (defaults `true`), but recommended if there is a possibility that an event could be created from Portal (or elsewhere), which would target this calendar (eg. via `target_everyone`). Given that it's a one-way sync, any creation of, or update on, events in this calendar would not be synced back to source, and could be overwritten when the calendar automatically re-syncs. `is_readonly` makes it so that this calendar cannot be targeted by events created outside of sync, but may not always be the correct option.
channel_ids _Optional	array	List of channel ids for which events linked to this calendar will be visible. Channels must belong to the community.

Returns

The newly created calendar-feed object with status code 201 (Created).

Notes:

type can be one of: GOOGLE_CALENDAR, MICROSOFT_CALENDAR, RELAY_CALENDAR, ICAL_CALENDAR

name could differ from display_name under some circumstances. For display purposes the display_name is preferred.

Retrieve Calendar Feed

curl "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "9b34f2c6-187e-4336-b06f-df295f5197e0",
  "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
  "name": "iCal test",
  "display_name": "iCal test",
  ...
  "events_count": 12,
  "type": "ICAL_CALENDAR",
  "channels": [
    {
      "id": "9b2f439b-2f1d-4c4e-b869-cabe0c646fbf",
      ...
    }
  ]
}

Retrieves a calendar feed.

Request

GET https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}

URL Parameters

Parameter	Description
id	The identifier of the `calendar-feed` which was returned upon linking.

Returns

A calendar-feed object (including channels) with status code 200 (OK). events_count is the number of public events in the calendar that are not deleted or cancelled.

Update Calendar Feed

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "name": "iCal Test Updated",
        "notify_synced_events": false,
        "is_sync_automatically": true,
        "target_everyone": true,
        "remove_event_channels": true,
        "channel_ids": []
    }'

{
  ...
  "name": "iCal Test Updated",
  "display_name": "iCal Test Updated",
  "is_sync_automatically": true,
  ...
  "target_everyone": true,
  "channels": []
}

Updates a calendar feed.

Request

PUT https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}

URL Parameters

Parameter	Description
id	The identifier of the `calendar-feed` which was returned upon linking.

Arguments (JSON)

Parameter	Type	Description
name _Required	string	A unique name for the calendar in context of the community.
notify_synced_events _Optional	bool	Whether to send scheduled reminder notifications to members for events which are newly synced for this calendar. Defaults to the calendar's current value.
is_sync_automatically _Optional	bool	Whether the calendar automatically re-syncs periodically. Defaults to the calendar's current value. Note that if `is_readonly` is not set during linking, this could result in re-synced data overriding any changes made to an event from Portal or elsewhere.
target_everyone _Optional	bool	Whether the events synced for this calendar automatically target everyone, and at the same time, whether events that target everyone should go into this calendar; provided `is_readonly` is `false`. Defaults to `false`.
channel_ids _Optional	array	List of channel ids for which events linked to this calendar will be visible. Channels must belong to the community. Note that omitting this removes all channels from the calendar (defaults to `[]`).
remove_event_channels _Optional	bool	If the channels on the calendar change, this flag can be used to specify that all events linked to the original channels, which are not present in the new list need to be unlinked from those channels. Defaults to `false`.

Returns

The updated calendar-feed object (including channels) with status code 200 (OK). The default calendar of a community cannot be updated (403).

Delete Calendar Feed

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "deleted": true,
  "unlinked": false
}

Deletes a specific calendar feed, and all related events permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}

URL Parameters

Parameter	Description
id	The identifier of the `calendar-feed` which was returned upon linking.

Query Parameters

Parameter	Description
unlink _Optional	If `true`, the calendar feed is unlinked from its source (see Unlink Calendar Feed) instead of being deleted. Defaults to `false`.

Returns

An object with id, deleted and unlinked attributes with status code 200 (OK). The default calendar of a community cannot be deleted (403).

Unlink Calendar Feed

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}/unlink" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "9b34f2c6-187e-4336-b06f-df295f5197e0",
  "unlinked": true
}

Unlinks a calendar feed from its source calendar and converts it to a d6 calendar. The calendar feed and its events are kept. Its name gets the suffix (unlinked), is_readonly is set to false and it no longer syncs from the original source.

Request

POST https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}/unlink

URL Parameters

Parameter	Description
id	The identifier of the `calendar-feed` which was returned upon linking.

Returns

An object with id and unlinked attributes with status code 200 (OK). The default calendar of a community cannot be unlinked (403).

Re-sync Calendar Feed

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}/sync" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Forces a resync of the calendar from the source calendar.

Request

POST https://relay-api.d6.co.za/api/business/v1/calendar-feeds/{id}/sync

URL Parameters

Parameter	Description
id	The identifier of the `calendar-feed` which was returned upon linking.

Returns

An empty response with status code 200 (OK).

List Calendar Feeds

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/calendar-feeds/list" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "sort": "-name",
        "per_page": "10",
        "page": "1",
        "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
        "channel_ids": []
    }'

{
  "data": [
    {
      "id": "96c46e66-fa34-4540-ba6c-66583c76a744",
      "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
      "name": "General",
      "display_name": "General",
      "source": null,
      "synced_at": "2023-03-16T09:52:34Z",
      "sync_failed_at": "2023-11-15T09:51:25Z",
      "sync_failed_reason": null,
      "is_sync_automatically": true,
      "created_at": "2022-07-13T09:21:39Z",
      "updated_at": "2023-11-15T09:51:25Z",
      "events_count": 20,
      "is_default": true,
      "is_readonly": false,
      "target_everyone": false,
      "type": "RELAY_CALENDAR",
      "channels": []
    },
    {
      "id": "9b34f2c6-187e-4336-b06f-df295f5197e0",
      "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
      "name": "iCal test",
      "display_name": "iCal test",
      "source": "9b34f2bf-ab99-4550-81e0-d2abc23d32ab",
      "synced_at": "2024-01-29T08:32:24Z",
      "sync_failed_at": null,
      "sync_failed_reason": null,
      "is_sync_automatically": true,
      "created_at": "2024-01-29T08:32:16Z",
      "updated_at": "2024-01-29T08:32:24Z",
      "events_count": 26,
      "is_default": false,
      "is_readonly": true,
      "target_everyone": false,
      "type": "ICAL_CALENDAR",
      "channels": [
        {
          "id": "9b2f439b-2f1d-4c4e-b869-cabe0c646fbf",
          "community_id": "966035e2-d9d8-44f4-b71c-6083872dc41d",
          "name": "Test Group",
          "invite_only": true,
          "is_hidden": false,
          "is_default": true,
          "can_leave": true,
          "created_at": "2024-01-26T12:43:20Z",
          "updated_at": "2024-01-26T12:43:20Z",
          "is_locked": false
        }
      ]
    }
  ],
  "pagination": {
    "total": 2,
    "count": 2,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1
  }
}

Returns a paginated list of all calendar_feeds for a community, with the community's default calendar first, then sorted by name by default. Each calendar_feed includes its channels.

Request

POST https://relay-api.d6.co.za/api/business/v1/calendar-feeds/list

Query Parameters

Parameter	Description
community_id _Required	The `community` to filter on
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of calendar feeds to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the calendar feeds by (ascending). Defaults to `name`. Sortable Properties: `name`, `synced_at`, `sync_failed_at`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `name` descending then by `created_at` ascending: `?sort=-name,created_at`.
search _Optional	Case insensitive string to search and filter calendar feeds by name.
channel_ids _Optional	Array of `channel` IDs to filter. Channels must belong to the community.

Returns

A data array of calendar_feed objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Events

The Events API allows one to create events on one or more community linked calendars without the requirement of a notice with event component.

The specific calendars on which the events are created and displayed (when add_to_calendar is set) is driven by a combination of channel and person_ids, or overridden with the the target_everyone flag.

Note also that repeat / recurrence_rules are expanded up to a year in the future so that a single incoming event containing those would result in the creation or modification of potentially many events, as dictated by those rules; hence, the response JSON (and corresponding events.changed webhook) contains a list of all events created, updated, or deleted from the request action if minimal_response = false.

If minimal_response = true it will only return the first (root) event created, updated, or deleted, and will switch to the event.created, event.updated, event.deleted webhooks as necessary. It is, therefore not recommended to use the minimal_response flag where recurrence rules (eg. updating instance only) might result in a splitting of events such that a number of events are created, deleted, or updated into separate root events.

Create a calendar event

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/events" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "deeb7fe5-da99-3d5a-a4d4-3e98644fc751",
            "title": "Rugby Training",
            "description": "Weekly Rugby Training",
            "address": "Knysna, WC",
            "start_date": "2022-11-25T10:00:00+02:00",
            "end_date": "2022-11-28T12:00:00+02:00",
            "all_day": false,
            "add_to_calendar": true,
            "remind_minutes": 0,
            "repeat": "WEEKLY",
            "channel_ids": [],
            "person_ids": [],
            "target_everyone": true,
            "recurrence_rules": "",
            "async": false            
        }'

{
  "created": [
    {
      "id": "9797d6fc-9dd7-4784-a53a-3bb2629a553f",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Weekly Rugby Training",
      "title": "Rugby Training",
      "start_date": "2022-11-25T08:00:00+00:00",
      "end_date": "2022-11-28T10:00:00+00:00",
      "all_day": false,
      "repeat": "WEEKLY",
      "remind_minutes": null,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": null,
      "cancelled_at": null,
      "created_at": "2022-10-26T11:33:47Z",
      "updated_at": "2022-10-26T11:33:47Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=WEEKLY",
        "DTSTART:20221125T080000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": false,
      "source": "d6",
      "channels": [],
      "persons": [],
      "is_locked": false
    },
    {
      "id": "9797d6fc-b4cf-4181-88fc-d21a7903c8b4",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Weekly Rugby Training",
      "title": "Rugby Training",
      "start_date": "2022-12-02T08:00:00+00:00",
      "end_date": "2022-12-05T10:00:00+00:00",
      "all_day": false,
      "repeat": "WEEKLY",
      "remind_minutes": null,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": "9797d6fc-9dd7-4784-a53a-3bb2629a553f",
      "cancelled_at": null,
      "created_at": "2022-10-26T11:33:47Z",
      "updated_at": "2022-10-26T11:33:47Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=WEEKLY",
        "DTSTART:20221125T080000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": false,
      "source": "d6",
      "channels": [],
      "persons": [],
      "is_locked": false
    },
  ...
  ],
  "deleted": [],
  "updated": []
}

Creates a new event.

Request

POST https://relay-api.d6.co.za/api/business/v1/events

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this event belongs to.
title _Required	string	The title of the event. Max 255 characters.
description _Optional	string	A complete description of the event.
address _Optional	string	The location of the event. Max 255 characters.
start_date _Required	string	Date and time on which the event starts. ISO 8601 with local timezone.
end_date _Required	string	Date and time on which the event ends. ISO 8601 with local timezone. Must be on or after start_date.
all_day _Optional	boolean	Whether the event spans the entire day(s) over the period from start to end dates. Note that this will modify start + end_dates to the start and end of those days. Default false.
add_to_calendar _Optional	boolean	Whether to make the event publically visible, based on the setting of target_everyone, channel_ids, and person_ids. Default false.
remind_minutes _Optional	integer	Number of minutes before the event start_date time to send a reminder. Note how all_day will adjust the start_date when setting this. Minimum 0. Defaults to 0 (no reminder).
reminder_method _Optional	string	The reminder method, one of `popup`, `email`.
repeat _Required	string	Basic event repeat options, one of NEVER, DAILY, WEEKLY, MONTHLY, ANNUALLY, WEEK_DAY, CUSTOM
recurrence_rules _Optional	array	Array of custom recurrence rule strings, use repeat = CUSTOM along with this
target_everyone _Optional	boolean	Whether this event is visible to everyone. Note that this will override channel + person_ids below. If no channel_ids or person_ids are provided, the event targets everyone regardless of this flag.
channel_ids _Optional	array	List of channel ids for which this event should be visible on linked calendars. Channels must belong to the event's community.
person_ids _Optional	array	List of person ids for which this event should be visible. Persons must belong to the event's community.
async _Optional	boolean	Whether to modify events asynchonously. Webhook can be used to obtain the full result. Default false.
minimal_response _Optional	boolean	Whether to return only the root event or all created/deleted/updated events. Defaults to false (return all events affected).
is_locked _Optional	boolean	Whether to lock these events so that only the API can make further changes to the object. Default false.

Returns

If async = false:

A list of created, updated, and deleted event objects with status code 201 (Created), if minimal_response = false, otherwise a single event object.

If async = true:

{ "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de" }

With status code 200 (OK)

Retrieve an event

curl "https://relay-api.d6.co.za/api/business/v1/events/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific event.

Request

GET https://relay-api.d6.co.za/api/business/v1/events/{id}

URL Parameters

Parameter	Description
id	The identifier of the `event` which was returned upon creation.

Returns

A single event object (including its channels, persons and published notice, if any), with status code 200 (OK). Returns 404 if the event has been deleted or cancelled.

Update an Event

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/events/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "title": "Rugby Training Updated",
            "description": "Monthly Rugby Training",
            "address": "Knysna, WC",
            "start_date": "2022-11-26T10:00:00+02:00",
            "end_date": "2022-11-27T12:00:00+02:00",
            "all_day": true,
            "add_to_calendar": true,
            "remind_minutes": 0,
            "repeat": "MONTHLY",
            "channel_ids": [],
            "person_ids": [],
            "target_everyone": true,
            "recurrence_rules": "",
            "instance_only": false,
            "instances_after": false,
            "async": false            
        }'

{
  "created": [
    {
      "id": "9797f7f7-3096-49e6-8219-27ceb5e6e75c",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Monthly Rugby Training",
      "title": "Rugby Training Updated",
      "start_date": "2022-12-25T00:00:00+00:00",
      "end_date": "2022-12-26T23:59:00+00:00",
      "all_day": true,
      "repeat": "MONTHLY",
      "remind_minutes": 20,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": "9797f6c8-356f-461a-a1e7-59fc79ce98bd",
      "cancelled_at": null,
      "created_at": "2022-10-26T13:06:00Z",
      "updated_at": "2022-10-26T13:06:00Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=MONTHLY",
        "DTSTART:20221125T000000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": true,
      "source": "d6",
      "channels": [],
      "persons": [],
      "is_locked": false
    },
    ...
  "deleted": [
    {
      "id": "9797f6c8-3dfd-49ef-b8f8-3e74b5ad8031",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Weekly Rugby Training",
      "title": "Rugby Training Updated",
      "start_date": "2022-12-26T08:00:00+00:00",
      "end_date": "2022-12-27T10:00:00+00:00",
      "all_day": false,
      "repeat": "MONTHLY",
      "remind_minutes": 0,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": "9797f6c8-356f-461a-a1e7-59fc79ce98bd",
      "cancelled_at": null,
      "created_at": "2022-10-26T13:02:41Z",
      "updated_at": "2022-10-26T13:06:00Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=MONTHLY",
        "DTSTART:20221126T080000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": false,
      "source": "d6",
      "channels": [],
      "persons": [],
      "is_locked": false
    },
    ...
  "updated": [
    {
      "id": "9797f6c8-356f-461a-a1e7-59fc79ce98bd",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Monthly Rugby Training",
      "title": "Rugby Training Updated",
      "start_date": "2022-11-25T00:00:00+00:00",
      "end_date": "2022-11-26T23:59:00+00:00",
      "all_day": true,
      "repeat": "MONTHLY",
      "remind_minutes": 20,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": null,
      "cancelled_at": null,
      "created_at": "2022-10-26T13:02:41Z",
      "updated_at": "2022-10-26T13:06:00Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=MONTHLY",
        "DTSTART:20221125T000000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": false,
      "source": "d6",
      "channels": [],
      "persons": [],
      "is_locked": false
    }
  ]
}

Updates a specific event.

Request

PUT https://relay-api.d6.co.za/api/business/v1/events/{id}

URL Parameters

Parameter	Description
id	The identifier of the `event` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
title _Optional	string	The title of the event. Max 255 characters.
description _Optional	string	A complete description of the event.
address _Optional	string	The location of the event. Max 255 characters.
start_date _Required	string	Date and time on which the event starts. ISO 8601 with local timezone.
end_date _Required	string	Date and time on which the event ends. ISO 8601 with local timezone. Must be on or after start_date.
all_day _Optional	boolean	Whether the event spans the entire day(s) over the period from start to end dates. Note that this will modify start + end_dates to the start and end of those days. Default false.
add_to_calendar _Optional	boolean	Whether to make the event publically visible, based on the setting of target_everyone, channel_ids, and person_ids. Default false.
remind_minutes _Optional	integer	Number of minutes before the event start_date time to send a reminder. Note how all_day will adjust the start_date when setting this. Minimum 0. Defaults to 0 (no reminder).
reminder_method _Optional	string	The reminder method, one of `popup`, `email`.
repeat _Required	string	Basic event repeat options, one of NEVER, DAILY, WEEKLY, MONTHLY, ANNUALLY, WEEK_DAY, CUSTOM
recurrence_rules _Optional	array	Array of custom recurrence rule strings, use repeat = CUSTOM along with this
target_everyone _Optional	boolean	Whether this event is visible to everyone. Note that this will override channel + person_ids below. If no channel_ids or person_ids are provided, the event targets everyone regardless of this flag.
channel_ids _Optional	array	List of channel ids for which this event should be visible on linked calendars. Channels must belong to the event's community.
person_ids _Optional	array	List of person ids for which this event should be visible. Persons must belong to the event's community.
async _Optional	boolean	Whether to modify events asynchonously. Webhook can be used to obtain the full result. Default false.
instance_only _Optional	boolean	Whether to update this instance of a recurring event (true) or all instances (false). Default false.
instances_after _Optional	boolean	Whether to update all instances of a recurring event after and including this one. Default false.
minimal_response _Optional	boolean	Whether to return only the root event or all created/deleted/updated events. Defaults to false (return all events affected).
is_locked _Optional	boolean	Whether to lock these events so that only the API can make further changes to the object. Defaults to the event's current value.

Returns

If async = false:

A list of created, updated, and deleted event objects with status code 200 (OK), if minimal_response = false, otherwise a single event object.

Returns 404 if the event has been deleted or cancelled.

If async = true:

{ "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de" }

With status code 200 (OK)

Delete an Event

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/events/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "created": [],
  "deleted": [
    {
      "id": "9797f6c8-356f-461a-a1e7-59fc79ce98bd",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Monthly Rugby Training",
      "title": "Rugby Training Updated",
      "start_date": "2022-11-25T00:00:00+00:00",
      "end_date": "2022-11-26T23:59:00+00:00",
      "all_day": true,
      "repeat": "MONTHLY",
      "remind_minutes": 20,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": null,
      "cancelled_at": null,
      "created_at": "2022-10-26T13:02:41Z",
      "updated_at": "2022-10-26T13:06:00Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=MONTHLY",
        "DTSTART:20221125T000000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": false,
      "source": "d6",
      "channels": [],
      "persons": [],
      "is_locked": false
    },
    ...
    ],
  "updated": []
}

Request

DELETE https://relay-api.d6.co.za/api/business/v1/events/{id}

URL Parameters

Parameter	Description
id	The identifier of the `event` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
instance_only _Optional	boolean	Whether to delete an instance of a recurring event (true) or all instances (false). Default false.
instances_after _Optional	boolean	Whether to delete all instances of a recurring event after and including this one. Default false.
minimal_response _Optional	boolean	Whether to return only the root event or all created/deleted/updated events. Defaults to false (return all events affected).

Returns

A list of created, updated, and deleted event objects with status code 200, if minimal_response = false, otherwise a single event object. Returns 404 if the event has already been deleted or cancelled.

List Events by Range

curl "https://relay-api.d6.co.za/api/business/v1/events/list/range?start_date=2021-11-25T10%3A00%3A00%2B02%3A00&end_date=2023-11-25T10%3A00%3A00%2B02%3A00&community_id=deeb7fe5-da99-3d5a-a4d4-3e98644fc751" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {   
      "id": "9797f7f7-3096-49e6-8219-27ceb5e6e75c",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Monthly Rugby Training",
      "title": "Rugby Training Updated",
      "start_date": "2022-12-25T00:00:00+00:00",
      "end_date": "2022-12-26T23:59:00+00:00",
      "all_day": true,
      "repeat": "MONTHLY",
      "remind_minutes": 20,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": "9797f6c8-356f-461a-a1e7-59fc79ce98bd",
      "cancelled_at": null,
      "created_at": "2022-10-26T13:06:00Z",
      "updated_at": "2022-10-26T13:06:00Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=MONTHLY",
        "DTSTART:20221125T000000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": true,
      "source": "d6",
      "is_locked": false
    },
...
}

Returns all events for a date range.

Request

GET https://relay-api.d6.co.za/api/business/v1/events/list/range

Query Parameters

Parameter	Description
community_id _Required	The identifier of the community that these events belong to.
start_date _Required	Date and time for which the event range starts. ISO 8601 with local timezone.
end_date _Required	Date and time for which the event range ends. ISO 8601 with local timezone.

Returns

A data array of event objects that overlap the range and have add_to_calendar set, ordered by start_date ascending. Status code: 200 (OK).

List Events

curl "https://relay-api.d6.co.za/api/business/v1/events/list?page=1&per_page=20&sort=-start_date" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {   
      "id": "9797f7f7-3096-49e6-8219-27ceb5e6e75c",
      "reference": "9797d6fc-9ed7-4784-a53a-3cb2629a55de",
      "calendar_feed_id": "96c82306-b1b4-4f57-8149-a9fbe8b1b8b3",
      "description": "Monthly Rugby Training",
      "title": "Rugby Training Updated",
      "start_date": "2022-12-25T00:00:00+00:00",
      "end_date": "2022-12-26T23:59:00+00:00",
      "all_day": true,
      "repeat": "MONTHLY",
      "remind_minutes": 20,
      "reminder_method": null,
      "tz_name": "+00:00",
      "utc_offset": "+00:00",
      "address": "Knysna, WC",
      "cancelled": false,
      "parent_id": "9797f6c8-356f-461a-a1e7-59fc79ce98bd",
      "cancelled_at": null,
      "created_at": "2022-10-26T13:06:00Z",
      "updated_at": "2022-10-26T13:06:00Z",
      "notice": null,
      "recurrence_rules": [
        "RRULE:FREQ=MONTHLY",
        "DTSTART:20221125T000000Z"
      ],
      "recurrence_string": null,
      "targets_everyone": true,
      "add_to_calendar": true,
      "source": "d6",
      "is_locked": false
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/events\/list?page=2"
    }
  }
}

Returns a paginated list of all events sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/events/list

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of events to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the events by (ascending). Defaults to `-updated_at`. Sortable Properties: `start_date`, `end_date`, `title`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `title` descending then by `created_at` ascending: `?sort=-title,created_at`.
search _Optional	Case insensitive string to search and filter events by title.
ids _Optional	List of event ids to filter on.
references _Optional	List of references to filter by.
person_ids _Optional	List of person ids to filter on.
channel_ids _Optional	List of channel ids to filter on.
community_ids _Optional	List of community ids to filter on.
parents_only _Optional	Whether to return only the root events. Defaults to false (0).
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `persons`, `channels`.

Returns

A data array of event objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).

Resources

Resources are the files and links a community publishes to its members (newsletters, policies, forms, fee documents and so on), shown in the app's Resources section. Resources are organised into folders, and each one is targeted at an audience and can carry a category and an expiry date.

These endpoints give you full management of a community's resource library: browse the folder tree, upload a file, set its audience, category and expiry, edit, move, bulk-action and delete.

Access

Read endpoints require the relay.business.read_only or relay.business.full_access scope. Write endpoints require relay.business.full_access. Each endpoint below states which it needs.
Every request carries a community_id (a query parameter on GET, a JSON field on POST/PATCH/DELETE). Your client must own or co-own that community, otherwise 403 (Forbidden) is returned.
A resource or folder that belongs to a different community than the community_id supplied returns 404 (Not Found).
Your client sees and manages every resource and folder in the community, and may target any channel or person in it. Resources and folders created by your client carry author_details.type of client.

GET and POST

Read endpoints marked GET | POST accept both verbs. The POST variant takes the same parameters as a JSON body, to avoid query string length limits.

Error codes

Business-rule violations return 400 (Bad Request) with a numeric code alongside the message:

{
  "message": "This resource has already been added.",
  "code": 4007
}

Code	Meaning
4001	Moving the folder would make it its own descendant.
4002	The `preview_token` does not match a delete preview of this folder, or has already been used.
4005	The resource cannot be retried because it is not in the `failed` state.
4006	The resource cannot be downloaded (it is a `link`, or a file with no stored upload).
4007	The resource cannot be added because it is not `pending`.
4008	The resource cannot be added because ingestion `failed`.
4009	The uploaded file's type is not supported. See Supported files.

The Resource Object

{
  "id": "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
  "type": "pdf",
  "name": "Term 1 Newsletter.pdf",
  "attributes": {
    "category": "Newsletters",
    "status": "ready",
    "fail_reason": null,
    "folder_id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "added_at": "2026-09-14T07:00:00Z",
    "added_by": null,
    "author_details": {
      "id": "8f1d2c3b-4a5e-6f70-8192-a3b4c5d6e7f8",
      "type": "client",
      "name": "Acme MIS",
      "image_url": null,
      "email": null,
      "role": null,
      "role_formatted": null
    },
    "is_stub": false,
    "needs_review": false,
    "expiry": {
      "evergreen": false,
      "expires_at": "2026-12-31T21:59:59Z",
      "expiring_soon": false,
      "auto": false,
      "reason": null,
      "display_tz": "Africa/Johannesburg"
    },
    "targeting": {
      "everyone": false,
      "channels": [
        {
          "id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
          "name": "Grade 1"
        }
      ],
      "persons": []
    },
    "size": 482113,
    "mime_type": "application/pdf",
    "downloadable": true
  }
}

Attribute	Type	Description
id	string	Unique identifier for the resource.
type	string	One of `pdf`, `docx`, `xlsx`, `image` or `link`.
name	string	The display name of the resource.
attributes.category	string	The resource category, or `null`. See Categories.
attributes.status	string	One of `pending`, `processing`, `ready`, `failed` or `expired`. See Lifecycle.
attributes.fail_reason	string	Why ingestion failed, when `status` is `failed`.
attributes.folder_id	string	The folder the resource is in, or `null` for the root.
attributes.added_at	string	When the resource was created.
attributes.added_by	string	The user identifier of the creator, or `null` when created by a client or integration.
attributes.author_details	object	Who created the resource. `type` is `user`, `client` or `integration`. `null` when the creator no longer exists.
attributes.is_stub	boolean	Whether the resource is a stub (little or no readable content).
attributes.needs_review	boolean	`true` when the content quality of the resource is poor.
attributes.expiry	object	`evergreen`, `expires_at` (the end of the expiry day in `display_tz`, in UTC), `expiring_soon` (a `ready` resource that expires within 14 days), `auto`, `reason` and `display_tz`.
attributes.targeting	object	The audience: `everyone`, plus the targeted `channels` and `persons` as `{ id, name }` objects.

The rest of attributes depends on type:

Type	Additional attributes
`pdf`, `docx`, `xlsx`	`size`, `mime_type`, `downloadable` (always `true`)
`image`	`size`, `mime_type`, `downloadable` (always `true`), `thumbnail_url`, `width`, `height` (the last three are currently always `null`)
`link`	`url`, `downloadable` (always `false`), `thumbnail_url`, `unfurl_metadata` (`{ title, description, site, image }` or `null`)

The Folder Object

{
  "id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "name": "2026",
  "parent_id": null,
  "child_folder_count": 0,
  "subtree_item_count": 0,
  "added_at": "2026-09-14T07:00:00Z"
}

Returned when creating or updating a folder. child_folder_count and subtree_item_count are always 0 here. The real counts appear on folder items in List Resources.

Resource Lifecycle

Creating a resource takes two steps, so Relay can read the document and suggest metadata before members can see it:

Upload. Upload the file with the Dedicated File Upload Endpoint, then call Create a Resource Upload with the returned file id. This creates a pending resource and starts reading the document.
Analyse (optional). Poll Retrieve a Resource Analysis for a suggested category, expiry and audience.
Add. Call Add a Resource with the chosen targeting, category and expiry. The resource becomes visible and moves from pending to processing to ready. A resource with no content to read (such as a link) goes straight to ready as a stub (is_stub: true).

A pending resource is not returned by List Resources or counted by Retrieve Resource Counts, so keep the id returned by Create a Resource Upload.

A resource that fails ingestion moves to failed. Call Retry a Resource to try again. A ready resource reports expired once its expiry date has passed.

Supported files

The uploaded file's MIME type determines the resource type:

MIME type	Type
`application/pdf`	`pdf`
`application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`docx`
`application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`xlsx`
`image/png`, `image/jpeg`, `image/gif`, `image/webp`	`image`

A file uploaded with the url argument of the Dedicated File Upload Endpoint becomes a link resource.

Other file types are not supported. Create a Resource Upload returns 400 (Bad Request) with code 4009 and no resource is created.

Field Reference

category: one of Newsletters, Policies, Calendar & Terms, Forms, Fees, Sport & Clubs or General.

targeting (on requests):

{
  "everyone": false,
  "channel_ids": ["12f6f48b-e219-4eec-b4ce-04cad170ffa8"],
  "person_ids": []
}

everyone is required. When everyone is true, channel_ids and person_ids must be empty. When everyone is false, at least one channel or person must be given. Channels and persons must belong to the community.

expiry (on requests):

{
  "mode": "dated",
  "date": "2026-12-31",
  "tz": "Africa/Johannesburg"
}

mode is evergreen (never expires) or dated. tz is an optional IANA timezone (default UTC). The resource expires at the end of date in tz.

On Add a Resource, date is required for dated. On Update a Resource and the bulk set_expiry action, a dated expiry without a date expires 21 days from now.

List Resources

curl "https://relay-api.d6.co.za/api/business/v1/resources?community_id={community_id}&folder_id={folder_id}&sort=-added" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
      "type": "folder",
      "name": "2026",
      "attributes": {
        "parent_id": null,
        "child_folder_count": 2,
        "subtree_item_count": 14
      }
    },
    {
      "id": "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
      "type": "pdf",
      "name": "Term 1 Newsletter.pdf",
      "attributes": {
        ...
      }
    }
  ],
  "pagination": {
    "total": 42,
    "count": 25,
    "per_page": 25,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "https://relay-api.d6.co.za/api/business/v1/resources?page=2"
    }
  }
}

Lists the resources in a folder. If any of search, category or status (other than all) is given, it instead searches the folder and every folder below it, returning resources only. Omit folder_id to search the whole community.

When browsing (no filters), page 1 also lists the folder's child folders first, as items with type of folder. pagination counts resources only, so page 1 can hold more than per_page items.

pending resources are never listed.

Scope: read

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources

Arguments

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
folder_id _Optional	string	The folder to browse or search. Omit or `null` for the root.
search _Optional	string	Search term, matched against the resource name and link URL. Switches to a search.
category _Optional	string	Filter by category.
status _Optional	string	One of `all`, `ready`, `processing`, `failed`, `expired`, `expiring` or `issues`. `expiring` is ready resources expiring within 14 days; `issues` is ready resources with poor content quality.
sort _Optional	string	One of `name`, `category`, `expires` or `added`. Prefix with `-` for descending. Default: `-added`.
page _Optional	integer	Page number. Default: `1`.
per_page _Optional	integer	One of `25`, `50`, `75` or `100`. Default: `25`.

Returns

A paginated list of folder items and resource objects with status code 200 (OK).

Retrieve Resource Counts

curl "https://relay-api.d6.co.za/api/business/v1/resources/counts?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "counts": {
    "all": 41,
    "ready": 38,
    "processing": 1,
    "failed": 1,
    "expired": 1,
    "expiring": 1,
    "issues": 0
  }
}

Returns the number of resources in each status for a folder and everything below it, or for the whole community when folder_id is omitted. pending resources are not counted.

all is the sum of ready, processing, failed and expired. expiring and issues are subsets of ready.

Scope: read

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources/counts

Arguments

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
folder_id _Optional	string	The folder to count from. Omit or `null` for the root.
search _Optional	string	Only count resources matching this search term.
category _Optional	string	Only count resources in this category.

Returns

A counts object with status code 200 (OK).

List Targetable Channels

curl "https://relay-api.d6.co.za/api/business/v1/resources/filters?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "channels": [
    {
      "id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
      "name": "Grade 1"
    },
    {
      "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
      "name": "Staff"
    }
  ]
}

Lists the channels a resource can be targeted at. This is every channel in the community.

Scope: read

Request

GET https://relay-api.d6.co.za/api/business/v1/resources/filters

Query Parameters

Parameter	Description
community_id _Required	The identifier of the community.

Returns

A channels array with status code 200 (OK).

Retrieve a Resource

curl "https://relay-api.d6.co.za/api/business/v1/resources/{id}?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": {
    "id": "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
    "type": "pdf",
    "name": "Term 1 Newsletter.pdf",
    "attributes": {
      ...
    },
    "is_stub": false,
    "deep_read": {
      "summary": "The Term 1 newsletter covers...",
      "sections": ["Principal's message", "Sport"],
      "document_type": "newsletter",
      "grades": ["Grade 1"],
      "year": 2026,
      "term": 1,
      "date": "2026-01-15",
      "language": "en",
      "test_questions": ["When does Term 1 end?"],
      "quality_tier": "good",
      "content_quality": {
        "status": "indexed",
        "indexed": true,
        "summary": "...",
        "issues": []
      },
      "freshness_class": "current",
      "content_scope": "...",
      "suggested_expiry": null,
      "key_info": ["Term 1 ends 28 March"],
      "broken_links": [],
      "is_stub": false
    }
  }
}

Retrieves a resource with Relay's analysis of its content in deep_read. deep_read is always null for a link. For files it is null unless the resource is ready or expired, and also when the analysis is not available. quality_tier is one of good, fair, poor or rejected.

When the resource is a stub, the response includes an X-Resource-Stub: true header.

Scope: read

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources/{id}

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments

Parameter	Type	Description
community_id _Required	string	The identifier of the community.

Returns

The resource object with deep_read and is_stub, under data, with status code 200 (OK).

Retrieve a Resource Analysis

curl "https://relay-api.d6.co.za/api/business/v1/resources/{id}/analysis?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": {
    "state": "suggested",
    "title": "Term 1 Newsletter",
    "language": "en",
    "document_type": "newsletter",
    "suggested_category": "Newsletters",
    "suggested_expiry": {
      "date": "2026-12-31",
      "reasoning": "...",
      "basis": "...",
      "source": "..."
    },
    "suggested_audience": {
      "everyone": true,
      "channel_ids": [],
      "person_ids": []
    }
  }
}

Returns Relay's suggested metadata for a pending resource. Poll this after creating a resource upload and use the suggestions to pre-fill Add a Resource.

state is one of analyzing, suggested, complete or failed. Suggestions fill in as analysis progresses. suggested_expiry is null until a document type is known, and its date may be null. suggested_audience is currently always everyone.

Scope: read

Request

GET https://relay-api.d6.co.za/api/business/v1/resources/{id}/analysis

URL Parameters

Parameter	Description
id	The identifier of the resource.

Query Parameters

Parameter	Description
community_id _Required	The identifier of the community.

Returns

The analysis under data with status code 200 (OK).

Download a Resource

curl "https://relay-api.d6.co.za/api/business/v1/resources/{id}/download?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": {
    "download_url": "https://..."
  }
}

Creates a short-lived signed URL to download a file resource. A link resource returns 400 (Bad Request) with code 4006.

Scope: read

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources/{id}/download

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments

Parameter	Type	Description
community_id _Required	string	The identifier of the community.

Returns

The download_url under data with status code 200 (OK).

Create a Resource Upload

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/resources/uploads" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "relay_uploads_file_id": "{file_id}",
            "folder_id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
        }'

{
  "data": {
    "id": "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
    "status": "pending"
  }
}

Step 1 of the lifecycle. Creates a pending resource from a file uploaded with the Dedicated File Upload Endpoint and starts analysing it. The resource is not visible to members until it is added.

Scope: write

Request

POST https://relay-api.d6.co.za/api/business/v1/resources/uploads

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
relay_uploads_file_id _Required	string	The identifier of the uploaded file.
folder_id _Optional	string	The destination folder. Omit or `null` for the root.
name _Optional	string	The resource name. Max length of 255 characters. Defaults to the file name.

Returns

The new resource's id and status under data with status code 201 (Created).

Add a Resource

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/resources/{id}/add" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "targeting": {
              "everyone": false,
              "channel_ids": ["22f6f48b-e219-4eec-b4ce-04cad170ffff"],
              "person_ids": []
            },
            "category": "Newsletters",
            "expiry": {
              "mode": "dated",
              "date": "2026-12-31",
              "tz": "Africa/Johannesburg"
            }
        }'

{
  "data": {
    "id": "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
    "type": "pdf",
    "name": "Term 1 Newsletter.pdf",
    "attributes": {
      "category": "Newsletters",
      "status": "processing",
      ...
    }
  }
}

Step 3 of the lifecycle. Sets the audience, category and expiry of a pending resource and makes it visible to members.

A resource that is already processing or ready returns 400 (Bad Request) with code 4007. A failed resource returns code 4008.

Scope: write

Request

POST https://relay-api.d6.co.za/api/business/v1/resources/{id}/add

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
targeting _Required	object	Who can see the resource. See targeting. There is no default audience.
expiry _Required	object	When the resource expires. See expiry.
category _Optional	string	The resource category.
name _Optional	string	The final resource name. Max length of 255 characters.
folder_id _Optional	string	The destination folder, or `null` for the root. Omit to keep the folder chosen at upload.

Returns

The updated resource object under data with status code 200 (OK).

Update a Resource

curl -X "PATCH" "https://relay-api.d6.co.za/api/business/v1/resources/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "category": "Policies",
            "expiry": {
              "mode": "evergreen"
            }
        }'

Updates a resource. Only the arguments you send are changed.

Scope: write

Request

PATCH https://relay-api.d6.co.za/api/business/v1/resources/{id}

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
category _Optional	string	The resource category, or `null`.
targeting _Optional	object	Who can see the resource. See targeting.
expiry _Optional	object	When the resource expires. See expiry.

Returns

The updated resource object under data with status code 200 (OK).

Retry a Resource

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/resources/{id}/retry" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8"
        }'

Retries analysis of a failed resource. Any other status returns 400 (Bad Request) with code 4005.

Scope: write

Request

POST https://relay-api.d6.co.za/api/business/v1/resources/{id}/retry

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.

Returns

The resource object, now processing, under data with status code 200 (OK).

Report a Resource Mistake

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/resources/{id}/report-mistake" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "category": "out_of_date",
            "message": "Superseded by the 2027 policy."
        }'

{
  "status": "sent"
}

Reports a mistake in Relay's analysis of a resource to the d6 support team.

Scope: write

Request

POST https://relay-api.d6.co.za/api/business/v1/resources/{id}/report-mistake

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
category _Required	string	One of `wrong_date_or_time`, `out_of_date`, `wrong_information`, `missing_something` or `something_else`.
message _Optional	string	Details of the mistake. Required when `category` is `something_else`. Max length of 2000 characters.

Returns

Status code 202 (Accepted).

Delete a Resource

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/resources/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8"
        }'

Deletes a resource. It is removed from the app and from chatbot search.

Scope: write

Request

DELETE https://relay-api.d6.co.za/api/business/v1/resources/{id}

URL Parameters

Parameter	Description
id	The identifier of the resource.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.

Returns

An empty response with status code 204 (No Content).

Bulk Resource Actions

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/resources/all/action/move" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "ids": [
              "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
              "c2a4d8b1-6e3f-4d2b-8c9f-1b2c3d4e5f6a"
            ],
            "folder_id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
        }'

{
  "data": {
    "results": [
      {
        "id": "b1f3c7a0-5d2e-4c1a-9b7e-0a1b2c3d4e5f",
        "status": "ok"
      },
      {
        "id": "c2a4d8b1-6e3f-4d2b-8c9f-1b2c3d4e5f6a",
        "status": "skipped",
        "reason": "not_found"
      }
    ]
  }
}

Applies one action to up to 200 resources. Duplicate ids are applied once. Each resource gets its own result, so an id that is not found in the community does not fail the whole request. The request is rejected with 422 (Unprocessable Entity) if any id is not a valid UUID or folder_id is not a folder in the community.

{verb} is one of:

Verb	Action
set_category	Set the `category` of each resource.
set_expiry	Set the `expiry` of each resource.
move	Move each resource to `folder_id`.
delete	Delete each resource.
download	Create a signed `download_url` for each file resource.

An unknown verb returns 404 (Not Found). This endpoint requires the write scope for every verb, including download. With the read scope only, use Download a Resource.

Scope: write

Request

POST https://relay-api.d6.co.za/api/business/v1/resources/all/action/{verb}

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
ids _Required	array	1 to 200 resource identifiers.
category _{Required for set_category}	string	The category to set.
expiry _{Required for set_expiry}	object	The expiry to set.
folder_id _Optional	string	For `move`: the destination folder. Omit or `null` to move to the root.
idempotency_key _Optional	string	Accepted but not yet enforced.

Returns

A results array under data with status code 200 (OK). Each result has an id and a status of ok, skipped or error. Results that are not ok include a reason: not_found (skipped), not_downloadable (skipped) or action_failed (error). Successful download results include a download_url.

Create a Folder

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/resources/folders" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "name": "2026 Newsletters",
            "parent_id": null
        }'

{
  "data": {
    "id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "name": "2026 Newsletters",
    "parent_id": null,
    "child_folder_count": 0,
    "subtree_item_count": 0,
    "added_at": "2026-09-14T07:00:00Z"
  }
}

Creates a folder.

Scope: write

Request

POST https://relay-api.d6.co.za/api/business/v1/resources/folders

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
name _Required	string	The folder name. Max length of 255 characters.
parent_id _Optional	string	The parent folder. Omit or `null` for the root.

Returns

The folder object under data with status code 201 (Created).

Update a Folder

curl -X "PATCH" "https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "name": "Renamed"
        }'

Renames and/or moves a folder. A move that would put a folder inside itself returns 400 (Bad Request) with code 4001.

Scope: write

Request

PATCH https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}

URL Parameters

Parameter	Description
id	The identifier of the folder.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
name _Optional	string	The new folder name. Max length of 255 characters.
parent_id _Optional	string	The new parent folder, or `null` for the root.

Returns

The folder object under data with status code 200 (OK).

Retrieve Folder Breadcrumbs

curl "https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}/breadcrumbs?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "9ca92b9e-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
      "name": "2026"
    },
    {
      "id": "0d1e2f3a-4b5c-6d7e-8f90-a1b2c3d4e5f6",
      "name": "Newsletters"
    }
  ]
}

Returns the folder's path, from the top-level folder down to the folder itself.

Scope: read

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}/breadcrumbs

URL Parameters

Parameter	Description
id	The identifier of the folder.

Arguments

Parameter	Type	Description
community_id _Required	string	The identifier of the community.

Returns

An array of { id, name } under data with status code 200 (OK).

Preview a Folder Delete

curl "https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}/delete-preview?community_id={community_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": {
    "folder_count": 3,
    "resource_count": 12,
    "sample": ["Newsletter.pdf", "Policy.pdf"],
    "preview_token": "{preview_token}"
  }
}

Shows what deleting a folder would remove, and returns the preview_token required by Delete a Folder. folder_count is the number of folders below this one, and sample lists up to 5 resource names in name order.

Each call returns a new preview_token. A token can be used once, and does not expire. Call this again just before deleting, so the counts reflect the folder's current contents.

Scope: write

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}/delete-preview

URL Parameters

Parameter	Description
id	The identifier of the folder.

Arguments

Parameter	Type	Description
community_id _Required	string	The identifier of the community.

Returns

The preview under data with status code 200 (OK).

Delete a Folder

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
            "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
            "preview_token": "{preview_token}"
        }'

{
  "data": {
    "deletion_id": "3e4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
    "status": "progressing"
  }
}

Deletes a folder with every folder and resource below it. The delete runs in the background: poll Retrieve a Folder Deletion with the returned deletion_id.

Call Preview a Folder Delete first to get a preview_token. A token that does not match a preview of this folder, or that has already been used, returns 400 (Bad Request) with code 4002.

Scope: write

Request

DELETE https://relay-api.d6.co.za/api/business/v1/resources/folders/{id}

URL Parameters

Parameter	Description
id	The identifier of the folder.

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community.
preview_token _Required	string	The token from the delete preview.

Returns

The deletion_id and status under data with status code 202 (Accepted).

Retrieve a Folder Deletion

curl "https://relay-api.d6.co.za/api/business/v1/resources/folders/deletions/{deletion_id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": {
    "id": "3e4f5a6b-7c8d-9e0f-a1b2-c3d4e5f6a7b8",
    "status": "done",
    "folder_count": 3,
    "resource_count": 12,
    "deleted_count": 12,
    "error_message": null
  }
}

Returns the progress of a folder delete. status is one of accepted, progressing, done or failed. folder_count and resource_count are the counts from the delete preview. deleted_count is the number of resources deleted so far, and error_message is set when status is failed.

Scope: read

Request

GET | POST https://relay-api.d6.co.za/api/business/v1/resources/folders/deletions/{deletion_id}

URL Parameters

Parameter	Description
deletion_id	The `deletion_id` returned by Delete a Folder.

Returns

The deletion under data with status code 200 (OK).

Apps

Apps refer to the applications attached to this community.

Retrieve an App

curl "https://relay-api.d6.co.za/api/business/v1/apps/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific app.

Request

GET https://relay-api.d6.co.za/api/business/v1/apps/{id}

Returns

The app object with status code 200 (OK).

List Apps

curl "https://relay-api.d6.co.za/api/business/v1/apps?sort=created_at&search=moc.tsirc.Relay&community_ids=c79503e8-cd70-3796-b2d4-9d2f4dace20b,95d372ec-5c85-46c3-a4de-3fe6058dbcaf" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"


[
  {
    "id": "316ca541-a7ac-30fb-9b7d-e8d02da3fca1",
    "bundle_id": "moc.tsirc.Relay",
    "platform": "iOS",
    "description": null,
    "min_supported_version": null,
    "created_at": "2022-05-16T09:24:27Z",
    "updated_at": "2022-05-16T09:24:27Z"
  }
]

Returns a list (not paginated) of all apps sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/apps

Query Parameters

Parameter	Description
sort _Optional	Comma separated string of properties to sort the apps by (ascending). Defaults to `-updated_at`. Sortable Properties: `created_at`, `updated_at`
search _Optional	Case insensitive string to search and filter apps `bundle_id`.
community_ids _Optional	Comma separated string of `community` IDs to filter.

Returns

A array of app objects. Status code: 200 (OK).

Webhooks

Listen for events on your account so your integration can automatically trigger reactions.

d6 uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events such as when a user opens a notice, interacts with a components or answers a form question.

Webhook Events

The following webhook events are currently supported:

Event	Description
community.created	When a `community` is created.
community.updated	When a `community` is updated.
community.deleted	When a `community` is deleted.
community.app.suspended	When app access for a `community` is suspended.
community.app.resumed	When app access for a `community` is resumed.
community.portal.suspended	When portal access for a `community` is suspended.
community.portal.resumed	When portal access for a `community` is resumed.
community_user.created	When a `community user` is created.
community_user.updated	When a `community user` is updated.
community_user.deleted	When a `community user` is detached from a community.
contact.created	When a `contact` is created.
contact.updated	When a `contact` is updated.
contact.deleted	When a `contact` is deleted.
tag.created	When a `tag` is created.
tag.updated	When a `tag` is updated.
tag.deleted	When a `tag` is deleted.
person.created	When a `person` is created.
person.updated	When a `person` is updated.
person.deleted	When a `person` is deleted.
channel.created	When a `channel` is created.
channel.updated	When a `channel` is updated.
channel.deleted	When a `channel` is deleted.
channel.expired	When a `channel` becomes expired, whether manually, on its `expires_at` date, or by a rollover.
channel.unexpired	When an expired `channel` has its expiry removed.
notice.created	When a `notice` is created.
notice.updated	When a `notice` is updated.
notice.published	When a `notice` is published.
notice.first.published	When a `notice` is published for the first time.
recipient.email.sent	When an email is successfully sent to a `notice recipient`.
recipient.email.delivered	When an email is successfully delivered to a `notice recipient`.
recipient.email.opened	When an email is opened by a `notice recipient`. BETA
recipient.email.rejected	When an email is rejected for a `notice recipient`.
recipient.email.bounced	When an email is bounced for a `notice recipient`.
recipient.email.complained	When an email is reported as spam/complained for a `notice recipient`.
recipient.sms.sent	When an SMS is successfully sent to a `notice recipient`.
recipient.sms.delivered	When an SMS is successfully delivered to a `notice recipient`.
recipient.sms.rejected	When an SMS is rejected for a `notice recipient`.
recipient.sms.replied	When an sms is replied to by a `notice recipient`.
recipient.app.push.sent	When a app notice push notification is successfully sent to a `notice recipient`.
recipient.app.delivered	When a notice is delivered to the app of a `notice recipient`.
recipient.app.opened	When a notice is opened on the app by a `notice recipient`.
recipient.responses	When a `notice recipient` answers response components (`response_text`, `response_boolean`, `response_choice`, `response_image`, `response_file`). The payload contains a `responses` array.
recipient.notice.fileOpened	When a `notice recipient` opens a `file` component.
recipient.notice.imageViewed	When a `notice recipient` view an `image` component.
recipient.notice.webFrameInteracted	When a `notice recipient` interacts with a `web_frame` component.
recipient.notice.locationInteracted	When a `notice recipient` interacts with a `location` component.
recipient.notice.youTubeVideoWatched	When a `notice recipient` watches a `you_tube_video` component.
recipient.notice.attachmentOpened	When a `notice recipient` opens an `attachment` component.
recipient.notice.urlOpened	When a `notice recipient` opens a `url` component.
contact.form.submission	When a `contact form` is submitted.
contact.form.category.created	When a `contact_form_category` is created.
contact.form.category.updated	When a `contact_form_category` is updated.
contact.form.category.deleted	When a `contact_form_category` is deleted.
resource.category.created	When a `resource_category` is created.
resource.category.updated	When a `resource_category` is updated.
resource.category.deleted	When a `resource_category` is deleted.
events.changed	When `events` are created, deleted, or updated.
event.created	When an `event` is created using the `minimal_mode` flag = true in request.
event.updated	When an `event` is updated using the `minimal_mode` flag = true in request.
event.deleted	When an `event` is deleted using the `minimal_mode` flag = true in request.

Webhooks Usage

{
    "type": "tag.created",
    "data": {
        "author": { // Can be null if created via API and not via Portal
            "id": "1386aa5b-3a2f-454d-94f7-50e7fe235716",
            "first_name": "Dirk",
            "last_name": "Coetzee",
            ...
            "created_at": "2021-05-26T21:52:10Z",
            "updated_at": "2021-06-03T12:55:43Z"
        }
        "tag": {
            "id": "9386aa5b-3a2f-454d-94f7-50e7fe235716",
            "name": "Tag #1",
            ...
            "created_at": "2021-05-26T21:52:10Z",
            "updated_at": "2021-06-03T12:55:43Z"
        }
    }
}

$signature = 'thesignaturefromtheheaderoftherequest';

$isValid = ($signature === hash_hmac('sha256', $request->getContent(), $configuredSigningSecret));

Webhooks always use the POST HTTP method with body of Content-Type: application/json.

This JSON body will contain a type attribute to determine the event type of the webhook (E.g tag.created) as well as a optional author attribute to identify the user who caused the action.

The webhook request will also contain a signature header value that needs to be used to determine whether the webhook is authentic and is actually coming from our system.

To verify the signature, take the body of the incoming request and create a HMAC SHA256 hash using the secret the webhook was setup with, then compare this hash with the Signature header value.

Create a Webhook

curl -X "POST" "https://relay-api.d6.co.za/api/business/v1/webhooks" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "enabled": true,
        "url": "https://example.url.to.target.d6.co.za",
        "events": [
            "community.created",
            "community.updated",
            "community.deleted"
        ]
    }'

{
    "id": "a395ff43-87d7-4d5b-a560-55c60099abca",
    "enabled": true,
    "url": "https://example.url.to.target.d6.co.za",
    "events": [
        "community.created",
        "community.updated",
        "community.deleted"
    ],
    "created_at": "2021-06-03T12:47:00Z",
    "updated_at": "2021-06-03T12:47:00Z"
}

Creates a new webhook.

Request

POST https://relay-api.d6.co.za/api/business/v1/webhooks

Arguments (JSON)

Parameter	Type	Description
enabled _Required	boolean	Whether the webhook should be enabled or not. Useful for pausing incoming webhooks.
url _Required	string	The target url of the webhook. Must be a valid URL. Max length of 2083 characters.
events _Required	array	Array of `events` this webhook should be triggered by. Must contain at least 1 of the supported webhook events.
secret _Optional	string	Min length of 6 and max length of 255 characters. Override the secret this webhook should use to calculate the `signature`. Useful if you want the webhook to go to third parties and don't want to disclose your own secret. If not provided, the account default secret will be used.

Returns

The newly created webhook object with status code 201 (Created).

Retrieve a Webhook

curl "https://relay-api.d6.co.za/api/business/v1/webhooks/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

Retrieves a specific webhook.

Request

GET https://relay-api.d6.co.za/api/business/v1/webhooks/{id}

URL Parameters

Parameter	Description
id	The identifier of the `webhook` which was returned upon creation.

Returns

The webhook object with status code 200 (OK).

Update a Webhook

curl -X "PUT" "https://relay-api.d6.co.za/api/business/v1/webhooks/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "enabled": false,
          "url": "https://example.new.url.d6.co.za"
         }'

{
  "id": "a395ff43-87d7-4d5b-a560-55c60099abca",
  "enabled": false,
  "url": "https://example.new.url.d6.co.za",
  ...
  "created_at": "2021-03-16T11:50:55Z",
  "updated_at": "2021-04-01T10:03:08Z"
}

Updates a specific webhook. Only specified arguments will be changed, ommitted arguments will remain unchanged.

Request

PUT https://relay-api.d6.co.za/api/business/v1/webhooks/{id}

URL Parameters

Parameter	Description
id	The identifier of the `webhook` which was returned upon creation.

Arguments (JSON)

Parameter	Type	Description
enabled _Optional	boolean	Whether the webhook should be enabled or not. Useful for pausing incoming webhooks.
url _Optional	string	The target url of the webhook. Must be a valid URL. Max length of 2083 characters.
events _Optional	array	Array of `events` this webhook should be triggered by. Must contain at least 1 of the supported webhook events.
secret _Optional	string	Min length of 6 and max length of 255 characters. Override the secret this webhook should use to calculate the `signature`. Useful if you want the webhook to go to third parties and don't want to disclose your own secret. If not provided, the account default secret will be used.

Returns

The updated webhook object with status code 200 (OK).

Delete a Webhook

curl -X "DELETE" "https://relay-api.d6.co.za/api/business/v1/webhooks/{id}" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
  "deleted": true
}

Deletes a specific webhook permanently.

Request

DELETE https://relay-api.d6.co.za/api/business/v1/webhooks/{id}

URL Parameters

Parameter	Description
id	The identifier of the `webhook` which was returned upon creation.

Returns

An object with an id and deleted attributes with status code 200 (OK).

List Webhooks

curl "https://relay-api.d6.co.za/api/business/v1/webhooks?page=1&per_page=20&sort=-url,created_at" \
     -H "Authorization: Bearer {ACCESS_TOKEN}" \
     -H "Accept: application/json"

{
  "data": [
    {
      "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
      ...
      "created_at": "2017-09-29T09:53:21Z",
      "updated_at": "2017-09-29T09:53:21Z"
    },
    {
      "id": "12f6ff6e-dbee-4408-a736-6a8d43ccaf3d",
      ...
      "created_at": "2017-09-22T08:29:00Z",
      "updated_at": "2017-09-22T08:29:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "count": 2,
    "per_page": 20,
    "current_page": 1,
    "total_pages": 2,
    "links": {
      "next": "http:\/\/relay-api.d6.co.za\/api\/business\/v1\/webhooks?page=2"
    }
  }
}

Returns a paginated list of all webhooks sorted by the most recently updated_at by default.

Request

GET https://relay-api.d6.co.za/api/business/v1/webhooks

Query Parameters

Parameter	Description
page _Optional	The page number to return (1-based). Defaults to `1`.
per_page _Optional	The amount of webhooks to return per page. Defaults to `15`.
sort _Optional	Comma separated string of properties to sort the webhooks by (ascending). Defaults to `-updated_at`. Sortable Properties: `url`, `created_at`, `updated_at`. *Hint:* Adding a `-` before the property name will reverse the sort order to descending. E.g. Sort by `url` descending then by `created_at` ascending: `?sort=-url,created_at`.
ids _Optional	Comma separated string of `webhook` IDs to filter.

Returns

A data array of webhook objects as well as a pagination object with properties to keep track of the pagination. Status code: 200 (OK).