NAV
shell

Introduction

Welcome to the Disciple API!

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl 'https://your-portal.disciplemedia.com/v1/users'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

Make sure to replace 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512 with your API key.

Disciple API uses API keys to allow access to the API. You can register a new API key at your admin panel.

Disciple API expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512

Rate Limits

The Disciple API limits the number of requests you can make within a given period of time. This limit will dynamically scale based upon the size of your community.

Rate Limit Errors

If you exceed your limit, we will return a 429 Throttled response. If you receive a response like this, you should wait for a short period of time before making any further requests. An exponential backoff is suggested so that you wait longer when you receive repeated errors.

Users

Get all Users (paginated)

curl 'https://your-portal.disciplemedia.com/v1/users/all'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "users": [
    {
      "id": 9,
      "email": "oberbrunner1wesmr@kleinratke.io",
      "display_name": "Mr. Wes Oberbrunner1",
      "last_active_at": "2019-02-26T12:59:27.887173Z",
      "created_at": "2019-02-26T12:59:27.886013Z",
      "last_platform": "ios",
      "avatar": {
        "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T125956Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=ec8420c453fb6b2fcdc915db63711547c74ba02e5821b298895bca9b76730b09"
      },
      "country": "US",
      "custom_user_values": {
        "1234" => "Mark"
      },
      "badges": [
        {
          "id": 1,
          "key": "custombadge",
          "name": "Custom Badge"
        }
      ],
      "ranking": {
        "score": 1234,
        "rank": 1
      }
    }
  ],
  "meta": {
    "total_count: 1
  }
}

This endpoint retrieves all users, paginated by the page (with a default value of 1) & per_page (with a default value of 50, possible values: between 1 and 50) params. The meta -> total_count value denotes the total count of Users.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/users/all

Query Parameters

Parameter Default Description
page 1 Currently requested page
per_page 50 Limit of records returned per page

Get Users by email

curl 'https://your-portal.disciplemedia.com/v1/users'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "users": [
    {
      "id": 9,
      "email": "oberbrunner1wesmr@kleinratke.io",
      "display_name": "Mr. Wes Oberbrunner1",
      "last_active_at": "2019-02-26T12:59:27.887173Z",
      "created_at": "2019-02-26T12:59:27.886013Z",
      "last_platform": "ios",
      "avatar": {
        "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T125956Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=ec8420c453fb6b2fcdc915db63711547c74ba02e5821b298895bca9b76730b09"
      },
      "country": "US",
      "custom_user_values": {
        "1234" => "Mark"
      },
      "badges": [
        {
          "id": 1,
          "key": "custombadge",
          "name": "Custom Badge"
        }
      ]
    }
  ]
}

This endpoint retrieves all users matching the specified criteria. Note: it is mandatory to set criteria; omitting it will not return all users.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/users

Query Parameters

Parameter Default Description
email null If set will return users matching this email (exact match)

Get a User

curl "https://your-portal.disciplemedia.com/v1/users/1" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "user": {
    "id": 8,
    "email": "upton4estell@nikolaus.info",
    "display_name": "Estell Upton4",
    "last_active_at": "2019-02-26T12:59:22.072375Z",
    "created_at": "2019-02-26T12:59:22.071949Z",
    "last_platform": "ios",
    "avatar": null,
    "country": "US",
    "ranking": null
  }
}

This endpoint retrieves a user.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user to retrieve

Get User by Customer SSO ID

curl 'https://your-portal.disciplemedia.com/v1/member_sso_users/<ID>'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above request returns JSON structured like this:

{
  "users": [
    {
      "id": 9,
      "email": "oberbrunner1wesmr@kleinratke.io",
      "display_name": "Mr. Wes Oberbrunner1",
      "last_active_at": "2019-02-26T12:59:27.887173Z",
      "created_at": "2019-02-26T12:59:27.886013Z",
      "last_platform": "ios",
      "avatar": {
        "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T125956Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=ec8420c453fb6b2fcdc915db63711547c74ba02e5821b298895bca9b76730b09"
      },
      "country": "US",
      "member_sso_id": "34ce0901716709580fa5",
      "custom_user_values": {
        "1234" => "Mark"
      },
      "badges": [
        {
          "id": 1,
          "key": "custombadge",
          "name": "Custom Badge"
        }
      ],
      "ranking": {
        "score": 1234,
        "rank": 1
      }
    }
  ]
}

The above request returns a 404 response if the user with specified ID is not found.

This endpoint retrieves a user by their Customer SSO ID.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/member_sso_users/<ID>

URL Parameters

Parameter Description
ID The Customer SSO ID of the user to retrieve

Create a User

curl -X "POST" "https://your-portal.disciplemedia.com/v1/users" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "email": "oberbrunner1wesmr@kleinratke.io",
  "display_name": "Mr. Wes Oberbrunner1",
  "password": "correct-horse-battery-staple"
}'

The above command returns a JSON response with HTTP code 201 structured like this:

{
  "user": {
    "id": 9,
    "email": "oberbrunner1wesmr@kleinratke.io",
    "display_name": "Mr. Wes Oberbrunner1",
    "last_active_at": "2019-02-26T12:59:27.887173Z",
    "created_at": "2019-02-26T12:59:27.886013Z",
    "last_platform": "ios",
    "avatar": null,
    "country": null,
    "member_sso_id": null,
    "custom_user_values": {
      "1234" => "Mark"
    },
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ],
    "ranking": {
      "score": 1234,
      "rank": 1
    }
  }
}

This endpoint creates a user.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/users

Request body

Parameter Type Required Description
email string yes The user's email
display_name string yes The user's display name
password string no The user's password. If not specified a random password will be generated. The generated password will not be returned in the response.

Endpoint error codes

Field Code Description
email taken The email has already been taken.
display_name taken The display name has already been taken.
password too_short The password is too short.

Update User by Customer SSO ID

curl 'https://your-portal.disciplemedia.com/v1/member_sso_users/<ID>'
     -X 'PATCH'
     -H 'Authorization: Bearer <CUSTOMER_SSO_SECRET>'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "user": {
    "email": "oberbrunner1wesmr@kleinratke.io"
  }
}'

The above request returns JSON structured like this:

{
  "user": {
    "id": 9,
    "email": "oberbrunner1wesmr@kleinratke.io",
    "display_name": "Mr. Wes Oberbrunner1",
    "last_active_at": "2019-02-26T12:59:27.887173Z",
    "created_at": "2019-02-26T12:59:27.886013Z",
    "last_platform": "ios",
    "avatar": {
      "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T125956Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=ec8420c453fb6b2fcdc915db63711547c74ba02e5821b298895bca9b76730b09"
    },
    "country": "US",
    "member_sso_id": "34ce0901716709580fa5",
    "custom_user_values": {
      "1234" => "Mark"
    },
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ],
    "ranking": {
      "score": 1234,
      "rank": 1
    }
  }
}

The above request returns a 404 response if the user with specified ID is not found.

This endpoint updates a user by their Customer SSO ID.

HTTP Request

PATCH https://your-portal.disciplemedia.com/v1/member_sso_users/<ID>

URL Parameters

Parameter Description
ID The ID of the user to update

Request body

Parameter Type Description
user[email] string The new email

Disable a User

curl 'https://your-portal.disciplemedia.com/v1/users/1/disable'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns an empty response with HTTP code 204. The above command returns a 404 response if the user with specified ID does not exist.

This endpoint disables a User.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/users/<ID>/disable

URL Parameters

Parameter Description
ID The ID of the user to disable

Request body

Parameter Type Required Description
unpublish_content boolean (default false) no If true, unpublishes all user's content

Reactivate a User

curl 'https://your-portal.disciplemedia.com/v1/users/1/enable'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns an empty response with HTTP code 204. The above command returns a 404 response if the user with specified ID does not exist.

This endpoint reactivates a User.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/users/<ID>/enable

URL Parameters

Parameter Description
ID The ID of the user to reactivate

Delete a User

curl 'https://your-portal.disciplemedia.com/v1/users/1'
     -X 'DELETE'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns an empty response with HTTP code 202. The above command returns a 404 response if the user with specified ID does not exist.

This endpoint schedules deletion of a User.

HTTP Request

DELETE https://your-portal.disciplemedia.com/v1/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user to delete

Request body

Parameter Type Required Description
delete_content boolean (default false) no If true, deletes all user's content
email_user boolean (default false) no If true, sends an email to the deleted user, notifying him about the account removal

Send Push Notification

curl 'https://your-portal.disciplemedia.com/v1/users/notifications'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "text":"Push notification message"
}'

The above request returns empty 204 response on success.

This endpoint sends push notification to selected users.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/users/notifications

Request body

Parameter Type Required Description
query string no Filter query. If not present, notification will be sent to all users. See Filters.
text string yes Body of push notifications, must have no more than 140 characters
action_link string no Action of push notification. See Actions.

Filters

Parameter Type Description
id string Filter users by comma separated IDs.
name string Partial match on user's name.
email string Partial match on users's email.
location string User's country. Must be in ISO 3166 Alpha-2 format.
registration date_range User's registration date. Must be in YYYY-MM-DD-YYYY-MM-DD (start_date-end_date) format. Start or end date can be omitted to indicate before (-YYYY-MM-DD) or after (YYYY-MM-DD-) respectively.
subscription boolean Filters users with active subscriptions.
active date_range User's last activity date. Must be in YYYY-MM-DD-YYYY-MM-DD (start_date-end_date) format. Start or end date can be omitted to indicate before (-YYYY-MM-DD) or after (YYYY-MM-DD-) respectively.
groups string Filter users by group membership. Multiple group keys can be specified, separated by commas. User must be a member of all specified groups.
trusted_reporter boolean Filters users that are trusted reporters.
can_livestream boolean Filters users with livestreaming permission.
verified_member boolean Filters users that are verified members.

The above filters can be combined into one filter query, separated by spaces. Multiple filters result in an implicit AND.

id:"1,2" name: "John" email:"example" location:"GB" registration:"-2018-07-31" subscription:"yes" active:"2019-07-23-" groups:"group1"

Actions

Clicking a push notification will trigger an action in application. Following actions are supported:

Custom User Fields

Get Custom User Fields

curl 'https://your-portal.disciplemedia.com/v1/custom_user_fields'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "custom_user_fields": [
    {
      "id": 1,
      "title": "Age",
      "value_type": "number",
      "mandatory": false,
      "show_on_onboarding": true,
      "visiblity": "private"
    },
    {
      "id": 2,
      "title": "Name",
      "value_type": "short_text",
      "mandatory": true,
      "show_on_onboarding": true,
      "visiblity": "public"
    },
    {
      "id": 3,
      "title": "Office",
      "value_type": "multiple_choice",
      "mandatory": false,
      "show_on_onboarding": false,
      "visiblity": "internal",
      "choices": [
        {
          "label": "Scranton"
        },
        {
          "label": "Stamford"
        }
      ]
    },
  ]
}

This endpoint retrieves all custom user fields.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/custom_user_fields

Update User's Custom User Fields

curl 'https://your-portal.disciplemedia.com/v1/users/1/custom_user_values'
     -X 'PATCH'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "values": {
    "1234": "value"
  }
}'

The above request returns empty 204 response on success.

This endpoint updates a user's custom user fields.

HTTP Request

PATCH https://your-portal.disciplemedia.com/v1/users/<ID>/custom_user_values

URL Parameters

Parameter Description
ID The ID of the user to edit

Request body

Parameter Type Required Description
values hash yes Dictionary of values. Key is the field ID.

Badges

Get Badges

curl 'https://your-portal.disciplemedia.com/v1/badges'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
}

The above command returns JSON structured like this:

{
  "badges": [
    {
      "id": 1,
      "key": "testbadge1",
      "name": "Test Badge 1"
    },
    {
      "id": 2,
      "key": "testbadge2",
      "name": "Test Badge 2"
    },
    {
      "id": 3,
      "key": "testbadge3",
      "name": "Test Badge 3"
    }
  ]
}

This endpoint retrieves all custom badges.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/badges

Update User's Badges

curl 'https://your-portal.disciplemedia.com/v1/users/1/badges'
     -X 'PATCH'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "badges": [
    {
      badge_id: 1
    },
    {
      "badge_id": 2,
      "remove": true
    }
  ]
}'

The above request returns empty 204 response on success.

This endpoint updates a user's badges.

Adding or removing badges is idempotent. Adding a badge or removing it will never fail and will result in a no-op if the user already owns the badge being added or doesn't own the badge being removed. Please note that requesting to add or remove a badge that does not exist is still an error.

HTTP Request

PATCH https://your-portal.disciplemedia.com/v1/users/<ID>/badges

URL Parameters

Parameter Description
ID The ID of the user to edit

Request body

Parameter Type Required Description
badges array yes An array of badges to add or remove
badges[]["badge_id"] integer yes The ID of the badge to add or remove
badges[]["remove"] boolean no If true the badge will be removed from the user

Endpoint error codes

Field Code Description
badge not_found The badge with specified ID could not be found.

Groups

Get All Groups

curl 'https://your-portal.disciplemedia.com/v1/groups'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "groups": [
    {
      "key": "group1",
      "name": "Group 1",
      "membership_type": "mandatory",
      "posting_permission": "everyone",
      "hottest_filter_enabled": false,
      "layout": "classic",
      "posts_count": 0,
      "members_count": null,
      "image": {
        "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test3.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T132637Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=cb395e9a99d1aef981bda6d8a54200ec8b850e95b00d0b10ff1698657730e7f0"
      }
    }
  ]
}

This endpoint retrieves all groups.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/groups

Create a Group

curl -X "POST" "https://your-portal.disciplemedia.com/v1/groups" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "name": "Group 1",
  "description": "Lorem ipsum dolor sit amet consectetur adipiscing",
  "membership_type": "mandatory",
  "posting_permissions": "everyone"
}'

The above command returns a JSON response with HTTP code 201 structured like this:

{
  "group": {
    "key": "group1",
    "name": "Group 1",
    "membership_type": "mandatory",
    "posting_permission": "everyone",
    "hottest_filter_enabled": false,
    "layout": "classic",
    "posts_count": 0,
    "members_count": null,
    "image": {
      "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test3.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T132637Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=cb395e9a99d1aef981bda6d8a54200ec8b850e95b00d0b10ff1698657730e7f0"
    },
    "header_image": {
      "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test3.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T132637Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=cb395e9a99d1aef981bda6d8a54200ec8b850e95b00d0b10ff1698657730e7f0"
    }
  }
}

This endpoint creates a group.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/groups

Request body

Parameter Type Required Description
name integer yes Name of the group
description string yes Description of the group
key string no Unique key, used in the URL to identify a group. Must be at least 3 characters long and can include characters from A to Z, numbers and an underscore. If not set, will be generated automatically
membership_type string yes Membership type. Must be one of: mandatory, private, public, secret
posting_permission string yes Who can post to the group. Must be one of: everyone, admins_only
layout string no (default classic Layout of group. Must be one of: classic, immersive. immersive layout can be only used when admins_only posting permissions are selected
hottest_filter_enabled boolean no (default false) Enable hottest content filtering
notify_on_every_member_post boolean no (default false) Notify all members on every post
include_in_unread_count boolean no (default false) Enable unread notification count
image_key string no The group's thumbnail image. See Uploads for more information on how to upload images
header_image_key string no The group's cover image. See Uploads for more information on how to upload images
position_before_key string no Key of the existing group which newly created group will be positioned before

Endpoint error codes

Field Code Description
image_key not_found The image upload could not be found.
image_key invalid_content_type The image upload's format is not supported
header_image_key not_found The image upload could not be found.
header_image_key invalid_content_type The image upload's format is not supported
key taken Group with specified key already exists
position_before_key not_found Group with specified key could not been found
not_permitted Maximum number of groups has been reached

Delete a Group

curl 'https://your-portal.disciplemedia.com/v1/groups/group1'
     -X 'DELETE'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns an empty response with HTTP code 204.

The above command returns a 404 response if the group with specified KEY does not exist.

This endpoint deletes a Group.

HTTP Request

DELETE https://your-portal.disciplemedia.com/v1/groups/<GROUP_KEY>

URL Parameters

Parameter Description
GROUP_KEY The key of the group to delete

Get User's Groups

curl 'https://your-portal.disciplemedia.com/v1/users/<USER_ID>/groups'
  -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "groups": [
    {
      "key": "group1",
      "name": "Group 1"
    }
  ]
}

This endpoint retrieves groups that the user is a member of.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/users/<USER_ID>/groups

Add a User to a Group

curl 'https://your-portal.disciplemedia.com/v1/groups/1/members'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "user_id": 1
}'

The above command adds the User to the Group and returns an empty response with HTTP code 204.

curl 'https://your-portal.disciplemedia.com/v1/groups/1/members'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "user_id": 1,
  "member_type": "admin"
}'

The above command adds the User to the Group as a group admin and returns an empty response with HTTP code 204.

This endpoint adds a User to a Group.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/groups/<GROUP_KEY>/members

URL Parameters

Parameter Description
GROUP_KEY The key of the group to add the user to

Request body

Parameter Type Description
user_id string The ID of the user to add to the group
member_type string (optional) One of: ["user", "admin"] - describes the newly added user membership type

Remove a User from a Group

curl 'https://your-portal.disciplemedia.com/v1/groups/1/members'
     -X 'DELETE'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns an empty response with HTTP code 204.

This endpoint removes a User from a Group.

HTTP Request

DELETE https://your-portal.disciplemedia.com/v1/groups/<GROUP_KEY>/members/<USER_ID>

URL Parameters

Parameter Description
GROUP_KEY The key of the group to remove the user from
USER_ID The ID of the user to remove from the group

Uploads

Upload keys

Endpoints that take uploads require the client to send them in the form of an upload key. An upload key is the path to the file in application's AWS S3 bucket.

Uploading files example: creating a post with an image

Retrieve temporary AWS credentials through Get Federated Credentials.

curl -X "POST" "https://your-portal.disciplemedia.com/v1/federated_credentials" \
     -H 'Authorization: Bearer e3572e67ed4958236dbedadc31848c06641e6bb10c04455d01dbdec4e9d18e26'

{
  "federated_credentials": {
    "policy": {
      "region": "us-east-1",
      "bucket": "disciple-production",
      "key_prefix": "dm-your-portal-production/direct_public_api_uploads/123"
    },
    "credentials": {
      "access_key_id": "KEY",
      "secret_access_key": "KEY",
      "session_token": "KEY",
      "expiration": "2019-07-26T12:45:31.000000Z"
    }
  }
}

Upload the file to provided location using these credentials. Make sure to set the Content-Type of the uploaded file.

AWS_ACCESS_KEY_ID=<KEY> AWS_SECRET_ACCESS_KEY=<KEY> AWS_SESSION_TOKEN=<KEY> aws s3 cp --content-type image/jpeg cat1.jpg s3://disciple-production/dm-your-portal-production/direct_public_api_uploads/123/1/cat1.jpg
upload: ./cat1.jpg to s3://disciple-production/dm-your-portal-production/direct_public_api_uploads/123/cat1.jpg

Use the S3 object's path as the upload key.

curl -X "POST" "https://your-portal.disciplemedia.com/v1/posts" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "group_key": "official",
  "author_id": 1,
  "text": "Lorem ipsum dolor sit amet consectetur adipiscing"
  "image_keys": ["dm-your-portal-production/direct_public_api_uploads/123/cat1.jpg"]
}'

Get Federated Credentials

curl -X "POST" "https://your-portal.disciplemedia.com/v1/federated_credentials" \
     -H 'Authorization: Bearer e3572e67ed4958236dbedadc31848c06641e6bb10c04455d01dbdec4e9d18e26'

The above command returns JSON structured like this:

{
  "federated_credentials": {
    "policy": {
      "region": "us-east-1",
      "bucket": "disciple-production",
      "key_prefix": "dm-your-portal-production/direct_public_api_uploads/123"
    },
    "credentials": {
      "access_key_id": "KEY",
      "secret_access_key": "KEY",
      "session_token": "KEY",
      "expiration": "2019-07-26T12:45:31.000000Z"
    }
  }
}

The above credentials can be used until 2019-07-26T12:45:31.000000Z to upload files to disciple-production S3 bucket in us-east-1 AWS region under the prefix dm-your-portal-production/direct_public_api_uploads/123.

This endpoint returns temporary security credentials. These credentials can be used to upload files to AWS S3.

Each API key has its own staging area for files. The files are periodically deleted so the client should not depend on the files remaining in the staging area for a duration longer than an hour.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/federated_credentials

Posts

Create a Post

curl -X "POST" "https://your-portal.disciplemedia.com/v1/posts" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "group_key": "official",
  "author_id": 1,
  "text": "Lorem ipsum dolor sit amet consectetur adipiscing"
}'

The above command returns an empty response with HTTP code 204.

This endpoint creates a post.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/posts

Request body

Parameter Type Required Description
author_id integer yes The ID of the user who is the post's author
group_key string yes The key of the group to create the post on
text string no The text of the post
image_keys string[] no The list of image upload keys. See Uploads.
video_keys string[] no The list of video upload keys. See Uploads.
attachments array no The list of attachment upload metadata. See Uploads.
attachments[]["key"] string yes The upload key for the file attachment. See Uploads.
attachments[]["filename"] string no A name to be displayed as the attachment file name. See Uploads.
action_button[text] string no Text of the action button
action_button[action] string no Action of the action button
notify boolean no (default false) If true, sends a push notification to group members
custom_notification_body boolean no If set, changes the text of the push notification
publish_at timestamp no If set, schedules the post to be published at the specified time
published_at timestamp no If set, the post will appear as if it was published at the specified time
external_key string no See External Keys

Endpoint error codes

Field Code Description
image_keys too_many A post cannot contain multiple images
video_keys too_many A post cannot contain multiple videos
no_content A post must contain text or media
attachments too_many A post cannot contain multiple attachments
author_id not_found The user who was specified as the author could not be found.
group_key not_found The post's group could not be found.
image_keys not_found The image upload could not be found.
video_keys not_found The video upload could not be found.
image_keys invalid_content_type The image upload's format is not supported
video_keys invalid_content_type The image upload's format is not supported
attachments invalid_content_type The attachment upload's format is not supported
publish_at past A post cannot be published in the past
author_id not_permitted_to_post The author must be the admin of the post's group

Unpublish a Post

curl -X "POST" "https://your-portal.disciplemedia.com/v1/posts/1/unpublish" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8'

The above command returns an empty response with HTTP code 204.

This endpoint unpublishes a post.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/posts/<ID>/unpublish

URL Parameters

Parameter Description
ID The ID of the post

Comments

Create a Comment

curl -X "POST" "https://your-portal.disciplemedia.com/v1/posts/1/comments" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
    -d $'{
  "author_id": 1,
  "text": "Lorem ipsum dolor sit amet consectetur adipiscing"
}'

The above command returns an empty response with HTTP code 204.

This endpoint creates a comment.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/posts/<POST_ID>/comments

URL Parameters

Parameter Description
POST_ID The ID of the post

Request body

Parameter Type Required Description
author_id integer yes The ID of the user who is the comment's author
text string no The text of the post
image_keys string[] no The list of image upload keys. See Uploads.
video_keys string[] no The list of video upload keys. See Uploads.
published_at timestamp no If set, the comment will appear as if it was published at the specified time
external_key string no See External Keys

Endpoint error codes

Field Code Description
image_keys too_many A post cannot contain multiple images
video_keys too_many A post cannot contain multiple videos
no_content A post must contain text or media
author_id not_found The user who was specified as the author could not be found.
image_keys not_found The image upload could not be found.
video_keys not_found The video upload could not be found.
image_keys invalid_content_type The image upload's format is not supported
video_keys invalid_content_type The image upload's format is not supported
author_id not_permitted_to_post The author must be the admin of the post's group

Unpublish a Comment

curl -X "POST" "https://your-portal.disciplemedia.com/v1/comments/1/unpublish" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8'

The above command returns an empty response with HTTP code 204.

This endpoint unpublishes a comment.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/comments/<ID>/unpublish

URL Parameters

Parameter Description
ID The ID of the comment

External Keys

External keys serve as unique identifiers that link resources in your system to external systems. They are:

External keys provide stable identifiers for importing content from external systems. Here’s how to use them:

  1. Call the Get Resource by External Key endpoint to verify if the resource already exists.
  2. If you receive a 404 response, use one of the available create endpoints to add the resource along with the external key.

Get Resource by External Key

curl 'https://your-portal.disciplemedia.com/v1/external_keys/post-abcdef-0001/resource'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "post": {
    "id": "1"
  }
}

curl 'https://your-portal.disciplemedia.com/v1/external_keys/comment-abcdef-0001/resource'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "comment": {
    "id": "1"
  }
}

This endpoint retrieves a resource by external key.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/external_keys/<EXTERNAL_KEY>/resource

URL Parameters

Parameter Description
EXTERNAL_KEY The external key of the resource

Products

Get Products

curl "https://your-portal.disciplemedia.com/v1/products" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "products": [
    {
      "id": 1,
      "name": "Platform course"
    }
  ]
}

This endpoint retrieves products.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/products/

Get User's Owned Products

curl "https://your-portal.disciplemedia.com/v1/users/1/products" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "product_ownerships": [
    {
      "product_id": 1,
      "product_name": "Platform course",
      "quantity": 1,
      "available_quantity": 1
    }
  ]
}

This endpoint retrieves products that the user owns.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/users/<ID>/products

URL Parameters

Parameter Description
ID The ID of the user

Update the available quantity of a User's Product

curl 'https://your-portal.disciplemedia.com/v1/users/1/products/1'
     -X 'PATCH'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "available_quantity": 0
}'

The above command returns JSON structured like this:

{
  "product_ownership": {
    "product_id": 1,
    "product_name": "Platform course",
    "quantity": 1,
    "available_quantity": 0
  }
}

The above request returns a 404 response if the user with specified ID does not own specified product.

This endpoint updates the available quantity of a User's Product.

HTTP Request

PATCH https://your-portal.disciplemedia.com/v1/users/<USER_ID>/products/<PRODUCT_ID>

URL Parameters

Parameter Description
USER_ID The ID of the user
PRODUCT_ID The ID of the product to update

Request body

Parameter Type Description
available_quantity integer The amount of available product quantity

Endpoint error codes

Field Code Description
available_quantity less_than_or_equal_to Available quantity must be less than or equal to quantity

Update all Users available quantity of Product to 0

curl 'https://your-portal.disciplemedia.com/v1/products/1/consume_all'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "affected_users": [
    {
      "id": 9,
      "email": "oberbrunner1wesmr@kleinratke.io",
      "display_name": "Mr. Wes Oberbrunner1",
      "last_active_at": "2019-02-26T12:59:27.887173Z",
      "created_at": "2019-02-26T12:59:27.886013Z",
      "last_platform": "ios",
      "avatar": {
        "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T125956Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=ec8420c453fb6b2fcdc915db63711547c74ba02e5821b298895bca9b76730b09"
      },
      "country": "US",
      "member_sso_id": "34ce0901716709580fa5",
      "custom_user_values": {
        "1234" => "Mark"
      },
      "badges": [
        {
          "id": 1,
          "key": "custombadge",
          "name": "Custom Badge"
        }
      ],
      "ranking": {
        "score": 1234,
        "rank": 1
      }
    }
  ]
}

The above request returns a 404 response if the product with specified ID does not exist.

This endpoint updates all Users available quantity of Product to 0.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/products/<ID>/consume_all

URL Parameters

Parameter Description
ID The ID of the product to update

Subscriptions

Get Subscriptions

curl "https://your-portal.disciplemedia.com/v1/subscriptions" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "subscriptions": [
    {
      "id": 1,
     "name": "Platform subscription"
    }
  ]
}

This endpoint retrieves all Subscriptions.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/subscriptions

Get User's Owned Subscriptions

curl "https://your-portal.disciplemedia.com/v1/users/1/subscriptions" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'

The above command returns JSON structured like this:

{
  "subscription_ownerships": [
    {
      "subscription_id": 1,
      "subscription_name": "Platform subscription",
      "started_at": "2019-06-10T12:11:31.728214Z",
      "expires_at": "2019-07-10T12:11:31.000000Z"
    }
  ]
}

This endpoint retrieves Subscriptions that the User owns.

HTTP Request

GET https://your-portal.disciplemedia.com/v1/users/<ID>/subscriptions

URL Parameters

Parameter Description
ID The ID of the user

Add Subscription to User

curl 'https://your-portal.disciplemedia.com/v1/users/1/subscriptions'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "subscription_id": 1,
  "expires_at": "2019-07-10T12:11:31.000000Z"
}'

The above command returns JSON structured like this:

{
  "subscription_ownership": {
    "subscription_id": 1,
    "subscription_name": "Platform subscription",
    "started_at": "2019-06-10T12:11:31.728214Z",
    "expires_at": "2019-07-10T12:11:31.000000Z"
  }
}

The above request returns a 404 response if the User with specified ID does not exist.

This endpoint creates subscription for specified User.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/users/<ID>/subscriptions

URL Parameters

Parameter Description
ID The ID of the user

Request body

Parameter Type Description
subscription_id integer ID of subscription to be added
expires_at timestamp Subscription's expiry date
override_managed_protection boolean Must be set to true in order to create subscription managed by Apple App Store or Google Play

Endpoint error codes

Field Code Description
subscription_id not_found Subscription with specified ID does not exist
expires_at later_than Expiry date must be later than the current date
not_permitted_to_create override_managed_protection parameter with true value must be provided because subscription is managed by Apple App Store or Google Play

Update the expiry date of a User's Subscription

curl 'https://your-portal.disciplemedia.com/v1/users/1/subscriptions/1'
     -X 'PATCH'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "expires_at": "2019-07-10T12:11:31.000000Z"
}'

The above command returns JSON structured like this:

{
  "subscription_ownership": {
    "subscription_id": 1,
    "subscription_name": "Platform subscription",
    "started_at": "2019-06-10T12:11:31.728214Z",
    "expires_at": "2019-07-10T12:11:31.000000Z"
  }
}

The above request returns a 404 response if the User with specified ID does not exist or does not own specified Subscription.

This endpoint updates the expiry date of a User's Subscription.

HTTP Request

PATCH https://your-portal.disciplemedia.com/v1/users/<USER_ID>/subscriptions/<SUBSCRIPTION_ID>

URL Parameters

Parameter Description
USER_ID The ID of the User
SUBSCRIPTION_ID The ID of the Subscription to update

Request body

Parameter Type Description
expires_at timestamp New expiry date
override_managed_protection boolean Must be set to true in order to update subscription managed by Apple App Store or Google Play

Endpoint error codes

Field Code Description
subscription_id not_found Subscription with specified ID does not exist
not_permitted_to_change override_managed_protection parameter with true value must be provided because subscription is managed by Apple App Store or Google Play

Expire User's Subscription

curl 'https://your-portal.disciplemedia.com/v1/users/1/subscriptions/1/expire'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'

The above command returns JSON structured like this:

{
  "subscription_ownership": {
    "subscription_id": 1,
    "subscription_name": "Platform subscription",
    "started_at": "2019-06-10T12:11:31.728214Z",
    "expires_at": "2019-07-10T12:11:31.000000Z"
  }
}

The above request returns a 404 response if the User with specified ID does not exist or does not own specified Subscription.

This endpoint expires User's Subscription.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/users/<USER_ID>/subscriptions/<SUBSCRIPTION_ID>/expire

URL Parameters

Parameter Description
USER_ID The ID of the User
SUBSCRIPTION_ID The ID of the Subscription to expire

Request body

Parameter Type Description
override_managed_protection boolean Must be set to true in order to expire subscription managed by Apple App Store or Google Play

Endpoint error codes

Field Code Description
subscription_id not_found Subscription with specified ID does not exist
not_permitted_to_change Parameter with true value must be provided because subscription is managed by Apple App Store or Google Play

Preregister a subscription

Preregister a subscription with an expiration date:

curl 'https://your-portal.disciplemedia.com/v1/subscriptions/1/preregistrations'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "email": "oberbrunner1wesmr@kleinratke.io"
  "expires_at": "2019-07-10T12:11:31.000000Z"
}'

The above command returns JSON structured like this:

{
  "subscription_preregistration": {
    "subscription": {
      "id": 1,
      "name": "premium"
    },
    "email": "oberbrunner1wesmr@kleinratke.io",
    "expires_in": nil
    "expires_at": "2019-06-10T12:11:31.728214Z"
  }
}

Preregister a subscription with a duration:

curl 'https://your-portal.disciplemedia.com/v1/subscriptions/1/preregistrations'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "email": "oberbrunner1wesmr@kleinratke.io"
  "expires_in": 2592000
}'

The above command returns JSON structured like this:

{
  "subscription_preregistration": {
    subscription": {
      "id": 1,
      "name": "premium"
    },
    "email": "oberbrunner1wesmr@kleinratke.io",
    "expires_in": 2592000
    "expires_at": nil
  }
}

The above request returns a 404 response if the Subscription with specified ID does not exist.

This endpoint preregisters a subscription for a user. The subscription will be added when a user account is registered using the specified email.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/subscriptions/<ID>/preregistrations

URL Parameters

Parameter Description
ID The ID of the subscription

Request body

Parameter Type Description
email string
expires_in integer Subscription's duration in seconds
expires_at timestamp Subscription's expiry date

Endpoint error codes

Field Code Description
email taken This subscription is already preregistered for this email
email used A user with this email already exists
expires_in greater_than Subscription's duration must be greater than zero
expires_at past Expiry date must be later than the current date
expires_in present Subscription's duration and expiration date cannot be present at the same time
expires_at present Subscription's duration and expiration date cannot be present at the same time
expires_in blank One of subscription's duration and expiration date must be present
expires_at blank One of subscription's duration and expiration date must be present

Remove a preregistered subscription

curl 'https://your-portal.disciplemedia.com/v1/subscriptions/1/preregistrations'
     -X 'POST'
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "email": "oberbrunner1wesmr@kleinratke.io"
  "expires_in": 2592000
}'

The above command returns an empty response with HTTP code 204. The above request returns a 404 response if the Subscription with specified ID does not exist.

This endpoint removes a preregistered subscription. Removing a preregistration is idempotent and will succeed even if it doesn't exist.

HTTP Request

POST https://your-portal.disciplemedia.com/v1/subscriptions/<ID>/preregistrations/delete_by_email

URL Parameters

Parameter Description
ID The ID of the subscription

Request body

Parameter Type Description
email string

Customer SSO

The Disciple application supports synchronisation of user accounts with the customer's system. To enable this feature the customer's system must provide an API with the following set of endpoints.

The following assumes the Customer SSO API is placed under the URL <CUSTOMER_SSO_BASE_URL>.

Disciple API

When this feature is enabled the following Disciple API endpoints become available:

Customer SSO ID

The users returned by the Customer SSO API are expected to have a unique identifier. The Disciple API records this identifier against users in its database. This identifier should not change once the user is created. The identifier is assumed to be a string.

Example JSON returned by Disciple API when Customer SSO is enabled:

{
  "users": [
    {
      "id": 9,
      "email": "oberbrunner1wesmr@kleinratke.io",
      "display_name": "Mr. Wes Oberbrunner1",
      "last_active_at": "2019-02-26T12:59:27.887173Z",
      "created_at": "2019-02-26T12:59:27.886013Z",
      "last_platform": "ios",
      "avatar": {
        "url": "https://disciple-development.s3.eu-west-1.amazonaws.com/test/test1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJMMN5US3EENR4M7A%2F20190226%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20190226T125956Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=ec8420c453fb6b2fcdc915db63711547c74ba02e5821b298895bca9b76730b09"
      },
      "country": "US",
      "member_sso_id": "34ce0901716709580fa5",
      "custom_user_values": {
        "1234" => "Mark"
      },
      "badges": [
        {
          "id": 1,
          "key": "custombadge",
          "name": "Custom Badge"
        }
      ],
      "ranking": {
        "score": 1234,
        "rank": 1
      }
    }
  ]
}

All responses from Disciple API that return a Disciple user will contain a key with this identifier.

Authentication

The Disciple application uses a shared secret when communicating with the Customer SSO API. The shared secret is included in all requests in a header that looks like following:

Authorization: Bearer 7a4bf31e0d9a2d19993c2683b3c5058cdba03b874087d514b62dddb2e934c091

The shared secret must be validated and requests that don't contain it or contain a secret that differs from the one that was exchanged with Disciple must be rejected.

The following assumes the secret is <CUSTOMER_SSO_SECRET>.

Get User by Email

curl 'https://<CUSTOMER_SSO_BASE_URL>/v1/users?email=oberbrunner1wesmr@kleinratke.io'
  -H 'Authorization: Bearer <CUSTOMER_SSO_SECRET>'

The above request must return the following JSON if a user with the specified email exists:

{
  "users": [
    {
      "id": "34ce0901716709580fa5",
      "email": "oberbrunner1wesmr@kleinratke.io"
    }
  ]
}

The above request must return the following JSON when there are no matching users:

{
  "users": []
}

The above request must NOT return more than one user. The Disciple application treats emails as unique and doesn't allow multiple users to have the same email.

This endpoint retrieves all users matching the specified email.

HTTP Request

GET https://CUSTOMER_SSO_BASE_URL/v1/users

Query Parameters

Parameter Default Description
email null If set will return users matching this email (exact match)

Get User by ID

curl 'https://<CUSTOMER_SSO_BASE_URL>/v1/users/34ce0901716709580fa5'
  -H 'Authorization: Bearer <CUSTOMER_SSO_SECRET>'

The above request must return the following JSON if a user with the specified ID is found:

{
  "user": {
    "id": "34ce0901716709580fa5",
    "email": "oberbrunner1wesmr@kleinratke.io"
  }
}

The above request must return a 404 response if the user with specified ID is not found.

This endpoint retrieves users by their Customer SSO ID.

HTTP Request

GET https://CUSTOMER_SSO_BASE_URL/v1/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user to retrieve

Create User

curl 'https://CUSTOMER_SSO_BASE_URL/v1/users'
     -X 'POST'
     -H 'Authorization: Bearer <CUSTOMER_SSO_SECRET>'
     -H 'Content-Type: application/json; charset=utf-8'
     -d $'{
  "email": "oberbrunner1wesmr@kleinratke.io"
}'

The above request must return the following JSON if the user was successfully created:

{
  "user": {
    "id": "34ce0901716709580fa5",
    "email": "oberbrunner1wesmr@kleinratke.io"
  }
}

The above request must return a 422 response if the user could not be created.

This endpoint creates users.

HTTP Request

POST https://CUSTOMER_SSO_BASE_URL/v1/users

Request body

Parameter Type Description
email string The email of the user

Webhooks

Overview

Webhooks notify the customer’s system about events that happen on the Disciple platform.

When the webhook fires, it performs a POST request to the configured URL. It will contain a JSON request body with the event details, and HTTP headers containing metadata about the request:

HTTP Header Description
X-Disciple-Event The event name.
X-Disciple-Delivery GUID of the webhook instance that can be used to deduplicate events in the case of retries.
X-Disciple-Signature The digital signature proving that it’s a genuine event from the Disciple platform.

Authentication

The Disciple signature is a HMAC hex digest that can be set up by providing a secret key to Disciple. We follow the same system as GitHub, who have provided some instructions on generating the key. The signature will then be generated with SHA1 using the provided secret key as the HMAC key.

Retries

If a webhook fails to receive a 2xx HTTP response, we will attempt to redeliver it periodically. These retries may happen out of order with other webhook deliveries. If the freshness of the data is important for your use-case, we recommend fetching up-to-date information from our API when you receive a webhook.

Future improvements

We will be adding new webhooks on a regular basis based on customer needs. Should a customer have a requirement for a webhook that is not planned or implemented we will consider all requests.

New User

{
  "id": 123,
  "email": "johnny@example.com",
  "created_at": "2019-01-01T00:00:00.000000Z",
  "member_sso_id": "456",
  "custom_user_values": [],
  "onboarding_completed": true,
  "badges": [
    {
      "id": 1,
      "key": "custombadge",
      "name": "Custom Badge"
    }
  ]
}

The New User event is triggered when a community member registers on the platform.

Field Presence Description
id Always The Disciple user ID.
email Always The user’s email address.
created_at Always When the user account was created.
member_sso_id When Magic Links SSO is enabled The customer user ID.
custom_user_values Always An array of Custom User Values objects. Normally empty for new users.
onboarding_completed Always Indicates whether the user has completed the onboarding process.

User Deleted

{
  "id": 123,
  "email": "johnny@example.com",
  "created_at": "2019-01-01T00:00:00.000000Z",
  "member_sso_id": "456",
  "custom_user_values": [],
  "onboarding_completed": true,
  "badges": [
    {
      "id": 1,
      "key": "custombadge",
      "name": "Custom Badge"
    }
  ],
  "event_source": "user"
}

The User Deleted event is triggered when a member account is deleted.

Field Presence Description
id Always The Disciple user ID.
email Always The user’s email address.
created_at Always When the user account was created.
member_sso_id When Magic Links SSO is enabled The customer user ID.
custom_user_values Always An array of Custom User Values objects
onboarding_completed Always Indicates whether the user has completed the onboarding process.
badges Always An array of Badge objects.
event_source Always An enum describing who/what triggered the deletion

Event source

Value Description
user User deleted their own account
console Community admin deleted the user's account
public_api Account deleted through this API
other Catch-all for other sources

User Updated

{
  "id": 123,
  "email": "johnny@example.com",
  "created_at": "2019-01-01T00:00:00.000000Z",
  "display_name": "Johnny Appleseed",
  "custom_user_values": [
    {
      "value": "Something the user typed in",
      "field_id": 456
    }
  ],
  "onboarding_completed": true,
  "badges": [
    {
      "id": 1,
      "key": "custombadge",
      "name": "Custom Badge"
    }
  ]
}

The User Updated event is triggered when a community member edits their profile.

Field Presence Description
id Always The Disciple user ID.
email Always The user’s email address.
created_at Always When the user account was created.
member_sso_id When Magic Links SSO is enabled The customer user ID.
custom_user_values Always An array of Custom User Values objects.
onboarding_completed Always Indicates whether the user has completed the onboarding process.

New Post

{
  "id": 789,
  "text": "Check out my photos!",
  "group": "some_group",
  "author": {
    "id": 123,
    "email": "johnny@example.com",
    "display_name": "Johnny Appleseed",
    "onboarding_completed": true
  },
  "images": [
    {
      "url": "https://cdn.example.com/images/photo1.jpg"
    },
    {
      "url": "https://cdn.example.com/images/photo2.jpg"
    }
  ],
  "videos": [],
  "published_at": "2019-01-01T00:00:00.000000Z"
}

{
  "id": 789,
  "text": "Check out my video!",
  "group": "some_group",
  "author": {
    "id": 123,
    "email": "johnny@example.com",
    "display_name": "Johnny Appleseed",
    "onboarding_completed": true
  },
  "images": [],
  "videos": [
    {
      "url": "https://cdn.example.com/images/video.mp4"
    }
  ],
  "published_at": "2019-01-01T00:00:00.000000Z"
}

The New Post event is triggered when a community member posts something to a group.

Field Presence Description
id Always The Disciple post ID.
text Always The body text of the comment.
group Always The group key.
author Always The user object as described above.
images Always An array of { url } objects pointing to images.
videos Always An array of { url } objects pointing to videos.
published_at Always When the post was created.

New Comment

{
    "id": 101112,
    "text": "That’s a great post!",
    "group": "fan",
    "author": {
        "id": 123,
        "email": "johnny@example.com",
        "display_name": "Johnny Appleseed",
        "onboarding_completed": true
    },
    "images": [],
    "videos": [],
    "published_at": "2019-01-01T00:00:00.000000Z",
    "commentable_id": 789,
    "commentable_type": "Post"
}

The New Comment event is triggered when a community member adds a comment to a post.

Field Presence Description
id Always The Disciple comment ID.
text Always The body text of the comment.
group Always The group key.
author Always The user object as described above.
images Always An array of { url } objects pointing to images.
videos Always An array of { url } objects pointing to videos.
published_at Always When the comment was created.
commentable_id Always The ID of what the comment is attached to.
commentable_type Always The type of thing the comment is attached to. This is always Post at present.

User’s Subscriptions Changed

{
  "user": {
    "id": 123,
    "email": "johnny@example.com",
    "created_at": "2019-01-01T00:00:00.000000Z",
    "display_name": "Johnny Appleseed",
    "custom_user_values": [],
    "onboarding_completed": true,
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ]
  },
  "subscription": {
    "name": "premium",
    "started_at": "2019-01-01T00:00:00.000000Z",
    "expires_at": "2019-01-01T00:00:00.000000Z"
  }
}

The User’s Subscriptions Changed event is triggered when a community member purchases a subscription; when the subscription is renewed for another billing period; and when the subscription expires.

Normally for a monthly subscription you would expect to see this event triggered once when the user first subscribes, again each month when the user successfully renews their subscription (with an updated expires_at timestamp), and finally once more when the user cancels and reaches the end of their final subscription period.

Field Presence Description
user Always The user object as described above.
subscription When the user has an active subscription
subscription.name Always The subscription name.
subscription.started_at Always When the subscription started.
subscription.expires_at Always When the current subscription period ends.

User subscription became active

{
  "user": {
    "id": 123,
    "email": "johnny@example.com",
    "created_at": "2019-01-01T00:00:00.000000Z",
    "display_name": "Johnny Appleseed",
    "custom_user_values": [],
    "onboarding_completed": true,
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ]
  },
  "subscription": {
    "name": "premium",
    "started_at": "2019-01-01T00:00:00.000000Z",
    "expires_at": "2019-01-01T00:00:00.000000Z"
  }
}

The User subscription became active event is triggered when a community member purchases / is manually assigned a subscription.

Normally for a monthly subscription you would expect to see this event triggered once when the user first subscribes.

Field Presence Description
user Always The user object as described above.
subscription When the user has an active subscription
subscription.name Always The subscription name.
subscription.started_at Always When the subscription started.
subscription.expires_at Always When the current subscription period ends.

User subscription became expired

{
  "user": {
    "id": 123,
    "email": "johnny@example.com",
    "created_at": "2019-01-01T00:00:00.000000Z",
    "display_name": "Johnny Appleseed",
    "custom_user_values": [],
    "onboarding_completed": true,
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ]
  },
  "subscription": {
    "name": "premium",
    "started_at": "2019-01-01T00:00:00.000000Z",
    "expires_at": "2019-01-01T00:00:00.000000Z"
  }
}

The User subscription became expired event is triggered when a community member's subscription expires / is manually disabled.

Normally for a monthly subscription you would expect to see this event triggered once when the month passes and the user does not prolong his subscription.

Field Presence Description
user Always The user object as described above.
subscription When the user has an active subscription
subscription.name Always The subscription name.
subscription.started_at Always When the subscription started.
subscription.expires_at Always When the current subscription period ends.

User’s Products Changed

{
  "user": {
    "id": 123,
    "email": "johnny@example.com",
    "created_at": "2019-01-01T00:00:00.000000Z",
    "display_name": "Johnny Appleseed",
    "custom_user_values": [],
    "onboarding_completed": true,
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ]
  },
  "product": {
    "name": "some_product",
    "created_at": "2019-01-01T00:00:00.000000Z"
  }
}

The User’s Products Changed event is triggered when a community member purchases a single product.

Field Presence Description
user Always The user object as described above.
product Always The product that has been purchased.
product.name Always The name of the product.
product.created_at Always When the product was purchased.

User Joined Group

{
  "id": 123,
  "member_type": "user",
  "user": {
    "id": 123,
    "email": "johnny@example.com",
    "created_at": "2019-01-01T00:00:00.000000Z",
    "display_name": "Johnny Appleseed",
    "custom_user_values": [],
    "onboarding_completed": true,
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ]
  },
  "group": {
    key: "community"
  }
}

The User Joined Group event is triggered when a community member joins or is added to a group.

The event is not triggered when:

Field Presence Description
id Always The Disciple group membership ID
member_type Always The type of membership. One of: ["user", "admin"]
user Always The user object as described above.
group Always The group key.

User Left Group

{
  "id": 123,
  "member_type": "user",
  "user": {
    "id": 123,
    "email": "johnny@example.com",
    "created_at": "2019-01-01T00:00:00.000000Z",
    "display_name": "Johnny Appleseed",
    "custom_user_values": [],
    "onboarding_completed": true,
    "badges": [
      {
        "id": 1,
        "key": "custombadge",
        "name": "Custom Badge"
      }
    ]
  },
  "group": {
    key: "community"
  }
}

The User Left Group event is triggered when a community member joins or is added to a group.

Field Presence Description
id Always The Disciple group membership ID
member_type Always The type of membership. One of: ["user", "admin"]
user Always The user object as described above.
group Always The group key.

Custom User Values

When a community has been configured with custom user fields for user profiles, community members that have filled any of these fields out will have these listed in the user object.

Field Presence Description
value Always The value the user entered.
field_id Always The Custom User Field ID.

Errors

The Disciple API users the following HTTP error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Check the response for the reason.
401 Unauthorized -- Your API key is missing or wrong.
404 Not Found -- The requested resource could not be found.
429 Throttled -- You have exceeded your rate limits. See Rate Limits.
500 Internal Server Error -- We had a problem with our server. Try again later.

Bad Request

Responses with HTTP status code 400 are returned when the request is not valid.

Examples:

Error response

curl -X "POST" "https://your-portal.disciplemedia.com/v1/posts" \
     -H 'Authorization: Bearer 7f7de4823fb0373ae1b2d34ce09013cb3055759d716709580fa5dbd86a9c9512' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "group_key": "official",
  "text": "Lorem ipsum dolor sit amet consectetur adipiscing"
}'

The above command returns JSON structured like this:

[
  {
    "code": "missing",
    "message": "is required",
    "field": "author_id"
  }
]
Field Type Description
code string The error code. See Generic error codes for errors that can happen on any endpoint or Endpoint error codes for endpoint specific errors (example).
field string Optional field (parameter) that this error is for. If not present then the error applies to the whole request.
message string Optional reason for the error. This field is present for debugging purposes only and its value may change at any time. It should not be displayed to end users.

Generic error codes

Code Description
missing The parameter is required.
too_long The parameter is too long. Maximum length is provided in error message.
too_short The parameter is too short. Minimum length is provided in error message.
blank The parameter can't be blank.
inclusion The parameter is not included in the list.

Timestamps

Example timestamp in ISO 8601 format:

2019-07-26T11:26:59.272Z

The Disciple API expects to receive timestamps formatted according to the ISO 8601 standard. The timestamps returned from the API will be formatted using the same standard.

shell