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

Users

Get Users

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

This endpoint retrieves all users matching the specified criteria.

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

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

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

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

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/user/<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

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/user/<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

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

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

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

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 Image upload key. See Uploads.
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
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

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

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

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

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

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

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

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?email=oberbrunner1wesmr@kleinratke.io'
  -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

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