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. Normally due to missing or malformed parameters.
401	Unauthorized	The request requires authentication. E.g No API key.
403	Forbidden	The server understood the request, but is refusing it or the access is not allowed.
404	Not Found	The resource was not found.
422	Unprocessable Entity	The server understood the request, but was unable to process the contained instructions.
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\/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
- links array which provides useful URLs to navigate pages
  - next Full URL to the next page (Ommitted if no next page)
  - prev 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 "image=" \
     -F "cover_image="
     -F "cover_image=" \
     -F "default_country_calling_code=27" \
     -F "feature_calendar_enabled=0" \
     -F "feature_resources_enabled=0" \
     -F "feature_gallery_enabled=1"

{
    "id": "92f6ff6e-dbee-4408-a736-6a8d43ccaf3f",
    "status": "active",
    "status_at": "2021-12-23T20:53:58Z", // When status was last changed
    "type": "school",
    "source": "manual",
    "locale": "en",
    "name": "Community Name",
    "email": "https:\/\/www.example.org",
    "phone_number": null,
    "website": null,
    "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",
    "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",
    "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,
    "timezone": "UTC",
    "app_download_url": "https:\/\/www.d6.co.za",
    "close_at": null,
    "created_at": "2021-12-23T20:53:57Z",
    "updated_at": "2022-05-05T07:21:53Z"
    "updated_at": "2022-05-05T07:21:53Z",
    "default_country_calling_code": 27,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "feature_calendar_enabled": false,
    "feature_resources_enabled": false,
    "feature_gallery_enabled": true
}

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'.
status _Optional	string	The status of the community. Available types: 'active', 'closed'. Defaults to 'active'.
email _Optional	string	The email address of the community.
phone_number _Optional	string	The phone number of the community.
website _Optional	string	The website of the community.
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
image_file_id _Optional	string	The file ID returned by our dedicated file upload endpoint. The `image`, `image_file_id` and `image_url` cannot be populated at the same time.
image_url _Optional	string	The image url. The `image`, `image_file_id` and `image_url` cannot be populated at the same time.
cover_image _Optional	file	The cover image of the community. Used in email headers and within the apps. Supported Formats: jpg, png, gif
cover_image_file_id _Optional	string	The file ID returned by our dedicated file upload endpoint. The `cover_image`, `cover_image_file_id` and `cover_image_url` cannot be populated at the same time.
cover_image_url _Optional	string	The cover image url. The `cover_image`, `cover_image_file_id` and `cover_image_url` cannot be populated at the same time.
app_ids _Optional	array	Array of App IDs this community should be attached to. These IDs will be provided to you.
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'.
create_initial_channels _Optional	boolean	Whether initial channels should be created with this community (E.g General Announcements).
d6_unique_zoho_reference _Optional	string	Internal usage.
account_contact_name _Optional	string	The name of the account contact.
account_contact_phone_number _Optional	string	The phone number for this account's contact.
account_contact_email _Optional	string	The email address for this account's contact.
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. The default timezone is `UTC`.
app_download_url _Optional	string	The url this app can be downloaded from.
general_enquiry_contact_person _Optional	string	The general enquiry contact person of this community.
general_enquiry_email _Optional	string	The general enquiry email address of the community.
general_enquiry_phone_number _Optional	string	The general enquiry phone number of the community.
default_country_calling_code _Optional	integer	A default country calling code used in member phone number validation and selection.
feature_calendar_enabled _Optional	boolean	Whether to enable / disable the calendar feature. Defaults to false.
feature_resources_enabled _Optional	boolean	Whether to enable / disable the resources feature. Defaults to false.
feature_gallery_enabled _Optional	boolean	Whether to enable / disable the gallery feature. Defaults to true.

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

POST 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

The community object with status code 200 (OK).

Update a Community

curl -X "PUT" "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

PUT 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.

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'.
status _Optional	string	The status of the community. Available types: 'active', 'closed'.
email _Optional	string	The email address of the community.
phone_number _Optional	string	The phone number of the community.
website _Optional	string	The website of the community.
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
image_file_id _Optional	string	The file ID returned by our dedicated file upload endpoint. The `image`, `image_file_id` and `image_url` cannot be populated at the same time.
image_url _Optional	string	The image url. The `image`, `image_file_id` and `image_url` cannot be populated at the same time.
cover_image _Optional	file	The cover image of the community. Used in email headers and within the apps. Supported Formats: jpg, png, gif
cover_image_file_id _Optional	string	The file ID returned by our dedicated file upload endpoint. The `cover_image`, `cover_image_file_id` and `cover_image_url` cannot be populated at the same time.
cover_image_url _Optional	string	The cover image url. The `cover_image`, `cover_image_file_id` and `cover_image_url` cannot be populated at the same time.
app_ids _Optional	array	Array of App IDs this community should be attached to. These IDs will be provided to you. *Hint:* Previously submitted `app_ids` must be present in this array. If not they will be detached from the community.
app_ids _Optional	array	Array of App IDs this community should be attached to. These IDs will be provided to you.
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.
general_enquiry_contact_person _Optional	string	The general enquiry contact person of this community.
account_contact_name _Optional	string	The name of the account contact.
account_contact_phone_number _Optional	string	The phone number for this account's contact.
account_contact_email _Optional	string	The email address for this account's contact.
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. The default timezone is `UTC`.
app_download_url _Optional	string	The url this app can be downloaded from.
general_enquiry_email _Optional	string	The general enquiry email address of the community.
general_enquiry_phone_number _Optional	string	The general enquiry phone number of the community.
default_country_calling_code _Optional	integer	A default country calling code used in member phone number validation and selection.
feature_calendar_enabled _Optional	boolean	Whether to enable / disable the calendar feature. Defaults to false.
feature_resources_enabled _Optional	boolean	Whether to enable / disable the resources feature. Defaults to false.
feature_gallery_enabled _Optional	boolean	Whether to enable / disable the gallery feature. Defaults to true.

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\/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/channels/list

Query Parameters

Parameter	Description
page _Optional	The page offset to use. Defaults to `0`.
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`, `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.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `apps`, `regions`.

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).

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"
        }'

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

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. 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 `channel` roles to be assigned to the community user. Available Channel Roles: `channel_moderator`, `channel_contributor`.

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"
    },
    {
      "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"
    }
  ],
  "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).
search _Optional	Case insensitive string to search and filter community users by email.
page _Optional	The page offset to use. Defaults to `0`.
per_page _Optional	The amount of community invites to return per page. Defaults to `15`.
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" "http://localhost:14200/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/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"
        }'

{
  "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"
        ]
      }
    }
  ],
  "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 containing the `channel` IDs this user should be associated with and a nested array of roles to be assigned to the `community_user`. Available Channel Roles: `channel_moderator`, `channel_contributor`.

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&perPage=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"
            ]
          }
        }
      ],
      "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.

Query Parameters

Parameter	Description
sort _Optional	Comma separated string of properties to sort the community users by (ascending).
search _Optional	Case insensitive string to search and filter community users by `first_name` or `last_name`.
page _Optional	The page offset to use. Defaults to `0`.
per_page _Optional	The amount of community users to return per page. Defaults to `15`.
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`, `channel_moderator`, `channel_contributor`.
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",
    "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"
    ],
    "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.
first_name _Optional	string	The first 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.
home_emails _Optional	array	Array of home/personal email addresses.
home_telephones _Optional	array	Array of home/personal telephone number strings preferably in E.164 format.
work_telephones _Optional	array	Array of work telephone number strings preferably in E.164 format.
note _Optional	string	Notes/description of the contact. Max length of 255 characters.
facebook_url _Optional	string	URL to the contact's Facebook page.
twitter_url _Optional	string	URL to the contact's Twitter page.

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.
first_name _Optional	string	The first 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.
home_telephones _Optional	array	Array of home/personal telephone number strings preferably in E.164 format.
work_telephones _Optional	array	Array of work telephone number strings preferably in E.164 format.
note _Optional	string	Notes/description of the contact. Max length of 255 characters.
facebook_url _Optional	string	URL to the contact's Facebook page.
twitter_url _Optional	string	URL to the contact's Twitter page.

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=-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\/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 offset to use. Defaults to `0`.
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: `prefix`, `first_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 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 _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.

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_identifer": "AB-122",
    "first_name": "Leroy",
    "last_name": "Jenkins",
    "email": "person@example.org",
    "phone_number": "+2761124222",
    "id_number": null,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "is_locked": false
}

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 _Required	string	The first name of the person. Max length of 255 characters.
last_name _Required	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)
email _Optional	string	The email address of the person.
phone_number _Optional	string	The 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.
channel_ids _Optional	array	Array of `channel` IDs this person should be attached to on creation.
tag_ids _Optional	array	Array of `tag` IDs this person should be attached to on creation.
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 `false`.
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.
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.

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

POST 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.

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 _Required	string	The first name of the person. Max length of 255 characters.
last_name _Required	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)
email _Optional	string	The email address of the person.
phone_number _Optional	string	The 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.
channel_ids _Optional	array	Array of `channel` IDs this person should be attached to on creation.
tag_ids _Optional	array	Array of `tag` IDs this person should be attached to on creation.
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 `false`.
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.

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
update_app_channel_subscriptions _Optional	boolean	Whether any app users linked to this person should have any channels unsubscribed on their behalf. Defaults to `false`.
notify_subscription_changes_via_app _Optional	boolean	If `update_app_channel_subscriptions` is `true`, whether app users should receive a notification about these channel unsubscriptions that happened on their behalf. Defaults to `false`.
update_app_community_subscriptions _Optional	boolean	Whether any app users linked to this person should have the community unsubscribed on their behalf. 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 this community unsubscription that happened on their behalf. Defaults to value of `notify_subscription_changes_via_app`.

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/{id}" \
      -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"
            ],
            "community_id": "4e7b1bdd-2fc4-3d0a-96f3-8ae77b30c749"
          }'

{
  "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/portal/v1/persons

Arguments (JSON)

Parameter	Type	Description
community_id _Required	string	The identifier of the community that this person belongs to.
person_ids _Required	array	Array of `person` IDs that were returned upon creation.

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\/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 offset to use. Defaults to `0`.
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`, `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 name.
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.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `channels`, `tags`.

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.

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",
    "invite_only": true,
    "is_hidden": false,
    "is_default": false,
    "can_leave": false,
    "tags": [],
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "is_locked": false
}

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 of the community that this channel belongs to.
name _Required	string	The name of the channel. Max length of 255 characters.
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 `false`.
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.

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

POST 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

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 _Required	string	The name of the channel. Max length of 255 characters.
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 `false`.
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.

Returns

The updated channel object 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\/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 offset to use. Defaults to `0`.
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.
expand _Optional	Comma separated string of relationships to include in the response. Expandable Relationships: `community`, `tags`.

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.

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 detch from this channel.
notify_subscription_changes_via_app _Optional	boolean	Whether the user should be notified via push notification and in feed message.

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", // Can be html, 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": "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,
    "choices": [
        "Apple",
        "Orange",
        "Strawberry"
    ]
}

{
    "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": "you_tube_video",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" // Needs to be a publically available YouTube url
}

{
    "type": "payment",
    "payment_type": "fixed", // fixed, open or itemised
    "title": "School Spring Walk Entry Fee",
    "amount_in_cents": 10000,
    "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 50 FOR NOW
        {
            "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`
`web_frame`	Akin to an iFrame, display an entire website within the notice.
`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.
`you_tube_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 50 images. Supported formats: jpeg, png, gif
`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 Web Page",
            "components": [
                {
                    "type": "text",
                    "text": "<b>Hello everyone!</b><br/><br/><p>This component supports basic HTML tags.</b>"
                },
                {
                    "type": "web_frame",
                    "url": "https://d6.co.za"
                }
            ]
        }'

{
    "id": "22f6f48b-e219-4eec-b4ce-04cad170ffff",
    "community_id": "12f6f48b-e219-4eec-b4ce-04cad170ffa8",
    "status": "Draft",
    "title": "A Notice With Some Text and a Web Page",
    "important": false,
    "target_everyone": false,
    "answerable": false,
    "payable": false,
    "published_at": null,
    "publish_platform_app": false,
    "publish_platform_sms": false,
    "publish_platform_email": false,
    "created_at": "2021-03-16T11:50:55Z",
    "updated_at": "2021-04-01T08:03:08Z",
    "deadline_at": "2022-02-01T09:02:01Z"
}

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 _Optional	array	Array of component objects to build the notice with. 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.

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

POST 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.

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_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 _Required	array	Array of platforms to target. Available platforms: `app`, `email`, `sms`.

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 '{
          "name": "Updated Name"
         }'

{
    "id": "96662f9c-974c-49c8-8315-f3de489f8ad7",
    "community_id": "95d372ec-5c85-46c3-a4de-3fe6058dbcaf",
    "status": "draft",
    "status_at": "2022-05-27T12:58:16Z",
    "title": "Testing Updated ALL COMPS!",
    "target_everyone": false,
    "important": false,
    "answerable": false,
    "payable": false,
    "created_at": "2022-05-27T12:58:16Z",
    "updated_at": "2022-05-27T12:59:00Z"
}

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 _Required	string	The title of the notice. Max length of 255 characters.
components _Optional	array	Array of edited components to build the notice with.

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.

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 _Required	array	Array of platforms to target. Available platforms: `app`, `email`, `sms`.
send_push_notification _Required	boolean	Whether app users should receive a push notification for this notice.
pin_notice _Required	boolean	Whether the notice should be pinned to the top of the screen for app users. `COMING SOON`

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\/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 offset to use. Defaults to `0`.
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`, `published_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`.

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/notice/{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,
      "notice_paid_at": null,
      "notice_answered_at": null,
      "parent_app_push_sent_at" : null,
      "parent_app_push_delivered_at" : null,
      "parent_app_sent_at" : null,
      "parent_app_delivered_at" : null,
      "parent_app_opened_at" : null,
      "parent_email_sent_at" : null,
      "parent_email_delivered_at" : null,
      "parent_email_opened_at" : null,
      "parent_email_bounced_at" : null,
      "parent_email_rejected_at" : null,
      "parent_email_complained_at" : null,
      "parent_sms_sent_at" : null,
      "parent_sms_delivered_at" : null,
      "parent_sms_rejected_at" : null,
      "parent_sms_replied_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\/v1\/notice/{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 offset to use. Defaults to `0`.
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`, `notice_paid_at`, `notice_answered_at`, `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`, `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 recipients by first or last names.
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`, `notice_paid_at`, `notice_answered_at`, `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`, `not_app_push_sent_at`, `not_app_push_delivered_at`, `not_app_sent_at`, `not_app_delivered_at`, `not_app_opened_at`, `not_email_sent_at`, `not_email_delivered_at`, `not_email_opened_at`, `not_email_bounced_at`, `not_email_rejected_at`, `not_email_complained_at`, `not_sms_sent_at`, `not_sms_delivered_at`, `not_sms_rejected_at`, `not_sms_replied_at`, `not_notice_paid_at`, `not_notice_answered_at`, `not_reminder_sent_at`, `not_parent_app_push_sent_at`, `not_parent_app_push_delivered_at`, `not_parent_app_sent_at`, `not_parent_app_delivered_at`, `not_parent_app_opened_at`, `not_parent_email_sent_at`, `not_parent_email_delivered_at`, `not_parent_email_opened_at`, `not_parent_email_bounced_at`, `not_parent_email_rejected_at`, `not_parent_email_complained_at`, `not_parent_sms_sent_at`, `not_parent_sms_delivered_at`, `not_parent_sms_rejected_at`, `not_parent_sms_replied_at`. All statuses starting with a `not_` prefix will filter statuses where the value is `null`.

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/notice/{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/notice/{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/notice/{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, 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.
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

Returns

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

Notes:

type can be one of: GOOGLE_CALENDAR, RELAY_CALENDAR, ICAL_CALENDAR

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

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}

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 `false`.
is_sync_automatically _Optional	bool	Whether the calendar automatically re-syncs periodically. Defaults to `true`. 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
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`.

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
}

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.

Returns

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

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" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "sync_source": true,
    }'

Forces a resync of the calendar on Relay API from either Relay Calendars API (sync_source = false) or from the source calendar (sync_source = true)

Request

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

Arguments (JSON)

Parameter	Type	Description
sync_source _Optional	bool	Defaults to `false`.

Returns

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 sorted by the most recently updated_at by default.

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 offset to use. Defaults to `0`.
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 channels 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.

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,
      "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": "weekly, starting from 2022-11-25 08:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": false,
      "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,
      "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": "weekly, starting from 2022-11-25 08:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": false,
      "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.
description _Optional	string	A complete description of the event.
address _Optional	string	The location of the event.
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.
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. Defaults to 0 (no reminder).
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. Default false.
channel_ids _Optional	array	List of channel ids for which this event should be visible on linked calendars.
person_ids _Optional	array	List of person ids for which this event should be visible.
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.

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, with status code 200 (OK)

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 $'{
            "community_id": "deeb7fe5-da99-3d5a-a4d4-3e98644fc751",
            "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,
      "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": "monthly, starting from 2022-11-25 00:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": true,
      "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,
      "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": "monthly, starting from 2022-11-26 08:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": false,
      "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,
      "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": "monthly, starting from 2022-11-25 00:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": false,
      "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 _Required	string	The title of the event.
description _Optional	string	A complete description of the event.
address _Optional	string	The location of the event.
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.
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. Defaults to 0 (no reminder).
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. Default false.
channel_ids _Optional	array	List of channel ids for which this event should be visible on linked calendars.
person_ids _Optional	array	List of person ids for which this event should be visible.
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.

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)

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,
      "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": "monthly, starting from 2022-11-25 00:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": false,
      "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.

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,
      "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": "monthly, starting from 2022-11-25 00:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": true
    },
...
}

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. 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,
      "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": "monthly, starting from 2022-11-25 00:00:00, forever",
      "targets_everyone": true,
      "add_to_calendar": true
    }
  ],
  "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 offset to use. Defaults to `0`.
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`, `location`, `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).

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

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

Returns

The app object with status code 200 (OK).

List Apps

curl "http://localhost:14200/api/business/v1/apps?sort=created_at&search=moc.tsirc.Relay&       community_ids=c79503e8-cd70-3796-b2d4-9d2f4dace20b,95d372ec-5c85-46c3-a4de-3fe6058dbcaf&expand=communities" \
     -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",
    "communities": [
      {
        "id": "50c53ab5-fdba-3a20-857e-763c09ec3f94",
        "status": "active",
        "status_at": "2022-05-16T09:24:28Z",
        "type": "business",
        "source": "manual",
        "invite_only": false,
        "locale": "en",
        "name": "Jast LLC",
        "email": "althea.ebert@raynor.net",
        "phone_number": "1-719-898-0851",
        "website": "http:\/\/www.ankunding.com\/eum-consectetur-illo-vel-aperiam-vitae-quaerat.html",
        "address": "6324 Moen Parkways Suite 757\nGusikowskiville, ID 21694-2895",
        "image": "https:\/\/cdnrly-staging.d6.co.za\/placeholder-logos\/logo13.png",
        "image_blurhash": null,
        "cover_image": null,
        "cover_image_blurhash": null,
        "email_cover_image": null,
        "d6_unique_zoho_reference": null,
        "account_contact_name": null,
        "account_contact_phone_number": null,
        "account_contact_email": null,
        "account_contact_notes": null,
        "app_accessible": true,
        "portal_accessible": true,
        "timezone": "UTC",
        "app_download_url": "https:\/\/d6.co.za\/education\/downloads",
        "ads_enabled": false,
        "ads_legacy_mobile_keyword": null,
        "ads_legacy_desktop_keyword": null,
        "close_at": null,
        "created_at": "2022-05-16T09:24:28Z",
        "updated_at": "2022-05-16T09:24:28Z"
      },
      {
        "id": "c79503e8-cd70-3796-b2d4-9d2f4dace20b",
        "status": "active",
        "status_at": "2022-05-16T09:24:28Z",
        "type": "unknown",
        "source": "manual",
        "invite_only": false,
        "locale": "en",
        "name": "Armstrong, Bailey and Dickens",
        "email": "sarah.ritchie@gmail.com",
        "phone_number": "+1-349-524-7988",
        "website": "https:\/\/bosco.com\/sed-reprehenderit-quibusdam-quos-quia.html",
        "address": "334 Novella Haven\nPort Darrinville, TN 25487",
        "image": "https:\/\/cdnrly-staging.d6.co.za\/placeholder-logos\/logo22.png",
        "image_blurhash": null,
        "cover_image": null,
        "cover_image_blurhash": null,
        "email_cover_image": null,
        "d6_unique_zoho_reference": null,
        "account_contact_name": null,
        "account_contact_phone_number": null,
        "account_contact_email": null,
        "account_contact_notes": null,
        "app_accessible": true,
        "portal_accessible": true,
        "timezone": "UTC",
        "app_download_url": "https:\/\/d6.co.za\/education\/downloads",
        "ads_enabled": false,
        "ads_legacy_mobile_keyword": null,
        "ads_legacy_desktop_keyword": null,
        "close_at": null,
        "created_at": "2022-05-16T09:24:28Z",
        "updated_at": "2022-05-16T09:24:28Z"
      }
    ]
  }
]

Returns a paginated list 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 persons by (ascending). Defaults to `-updated_at`. Sortable Properties: `created_at`, `updated_at`
search _Optional	Case insensitive string to search and filter apps `bundle_id`.
ids _Optional	Comma separated string of `app` 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 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.
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.
notice.created	When a `notice` is created.
notice.published	When a `notice` is published.
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.response.text	When a `notice recipient` answers a `response_text` component.
recipient.response.boolean	When a `notice recipient` answers a `response_boolean` component.
recipient.response.choice	When a `notice recipient` answers a `response_choice` component.
recipient.response.image	When a `notice recipient` answers a `response_image` component.
recipient.response.file	When a `notice recipient` answers a `response_file` component.
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 SHA256 hash using the secret the webhook was setup with, then compare this hash with the signature.

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.
events _Required	array	Array of `events` this webhook should be triggered by.
secret _Optional	string	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

POST 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.
events _Optional	array	Array of `events` this webhook should be triggered by.
secret _Optional	string	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=-name,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\/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 offset to use. Defaults to `0`.
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).