CMNTY API

API Endpoint
https://yourdomain

Welcome to the CMNTY API.

Current Version

You must begin by setting a version of the API in the Accept header of your requests. If you do not set the version, you will always use the latest version of the API, however, we strongly encourage you to explicitly request the v1 version of the API via the Accept header in your requests.

Accept: application/vnd.cmnty.v1+json

Schema

All API access must happen over HTTPS from the URL https://yourdomain. Data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

Timestamps are returned in ISO 8601 format.

YYYY-MM-DDTHH:MM:SSZ

Content-type

API POST requests must contain the appropriate content-type.

Content-type: application/json

API POST requests without the appropriate content-type will return a 400 Bad request error.

HTTP/1.1 400 Bad request

{
  "code": "ERROR-0001",
  "message": "Bad request",
}

HTTP Verbs

Verb Description
HEAD Can be issued against any resource to get just the HTTP header info.
GET Used for retrieving resources.
POST Used for creating resources.
PATCH Used for updating resources.
DELETE Used for deleting resources.

Authentication

Authentication is handled through Basic Authentication with an username and password. You can go to Configure > API > API Client to create a new client within your platform. You have to add the authorization header to all your requests.

Authorization: Basic Y21udHk6cGxhdGZvcm0=

You can test the API by performing a GET request to the https://yourdomain endpoint, which will return a 200 OK.

HTTP/1.1 200 OK

{
  "name": "yourplatform",
  "tagline": "Welcome to the API!"
}

Accessing the API without being authenticated properly will return a 401 Unauthorized.

HTTP/1.1 401 Unauthorized

{
  "code": "AUTHENTICATION-0101",
  "message": "Incorrect credentials"
}

Accessing the API without being on the Premium plan will return a 403 Forbidden.

HTTP/1.1 403 Forbidden

{
  "code": "ERROR-0004",
  "message": "You must be on a Premium plan to access our API."
}

Multiple requests without proper authentication will return a 429 Too many requests.

HTTP/1.1 429 Too many requests

{
  "code": "AUTHENTICATION-0102",
  "message": "Too many invalid authentication attempts."
}

Active modules

CMNTY Platform allows you to disable certain parts of your community in Platform Configuration section of the Admin interface. Our API responds to this configuration, and if a request is made to a disabled part of the Platform, the response will be 409 Conflict.

HTTP/1.1 409 Conflict

{
  "code": "ERROR-0006",
  "message": "The forum module is turned off. Turn this module on in your platform configuration."
}

Pagination

Requests that return multiple items will be paginated to 10 items by default. You can change the limit parameter up to a maximum of 250 to get more items at once. You can set a different offset to define your starting point. By default this is 0.

The Link header includes pagination information:

Link: <https://...?offset=20>; rel="next", <https://...?offset=50>; rel="last"

This Link response header contains one or more Hypermedia link relations, some of which may require expansion as URI templates.

The possible rel values are:

Name Description
next The link relation for the immediate next page of results.
last The link relation for the last page of results.
first The link relation for the first page of results.
prev The link relation for the immediate previous page of results.

X-Total-Count Header

The X-Total-Count header includes information about the amount of items:

X-Total-Count: 53

Rate Limiting

You can make up to 250 authenticated requests per hour. (Please contact us if you want to discuss raising the limit.) For unauthenticated requests, the rate limit allows you to make up to 10 requests per hour.

You can check the returned HTTP headers of any API request to see your current rate limit status:

HTTP/1.1 200 OK
X-RateLimit-Limit: 250
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873

The headers tell you everything you need to know about your current rate limit status:

Header Name Description
X-RateLimit-Limit The maximum number of requests that the client is permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

Crossing the rate limit will return a 429 Too many requests.

HTTP/1.1 429 Too many requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266

{
  "code": "ERROR-0002",
  "message": "API request limit exceeded"
}

Timezones

Timestamps are returned in ISO 8601 format as UTC. The API currently does not take the Timezone header in to account.

User-Agent

We request you to set the name of your application in the User-Agent header, so your traffic becomes recognizable for us.

User-Agent: Name of my application

System

GET https://yourdomain/system/details
Responses200
Headers
Content-Type: application/json
Body
{
  "database_size": 23342,
  "content_size": 3454353
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "database_size": {
      "type": "number",
      "description": "Size of the database, in bytes"
    },
    "content_size": {
      "type": "number",
      "description": "Size of Platform's content, in bytes"
    }
  }
}

Get Platform details
GET/system/details

Retrieve information about Platform’s disk usage.

Data in response

  • database_size: 23342 (number) - Size of the database, in bytes

  • content_size: 3454353 (number) - Size of Platform’s content, in bytes


Invites

GET https://yourdomain/user/invites?offset=0&limit=10
Responses200
Headers
Content-Type: application/json
Link: <https://../user/invites>;rel="first", <https://../user/invites>;rel="previous", <https://../user/invites>;rel="next", <https://../user/invites>;rel="last"
X-Total-Count: 12
Body
[
  {
    "language": "en",
    "subject": "Your invite is awaiting",
    "message": "Hi, <br />please join our community",
    "role": {
      "id": 123,
      "name": "Community Manager",
      "key": "community-manager"
    },
    "groups": [
      1
    ],
    "email_address": "support@cmnty.com",
    "token": "cmnty348dfg3",
    "id": 123,
    "status": "accepted",
    "sent_count": 1,
    "self": "https://../api/user/invites/{id}",
    "groups_url": "https://../api/user/invites/{id}/groups",
    "accept_url": "https://../authorize/invite/cmnty348dfg3",
    "decline_url": "https://../authorize/decline/cmnty348dfg3",
    "created_at": "2017-02-28T09:39:33+00:00",
    "last_sent_at": "2017-02-28T09:39:33+00:00"
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get invites
GET/user/invites{?offset,limit}

Retrieve all invites from the platform. By default no filter is applied.

URI Parameters
HideShow
offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination

filter
array[string] (optional) Example: [status][]=accepted
  • status - To filter on the status of the invite [ open | accepted | declined ]

  • language - To filter on the language of the invite

  • role - To filter on the role which the user will receive on accepting the invite

sort
string (optional) Default: id Example: id,-created_at

The way the invites are sorted. Use a minus sign (-) in front of the field to sort descending

  • id - To sort on the ID of the invite

  • created_at - To sort on the creation date of the invite


POST https://yourdomain/user/invites?send-email=0
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "language": "en",
  "subject": "Your invite is awaiting",
  "message": "Hi, <br />please join our community",
  "role": "community-manager",
  "groups": [
    1
  ],
  "email_address": "support@cmnty.com",
  "token": "cmnty348dfg3"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "subject": {
      "type": "string",
      "description": "Subject of the invite email"
    },
    "message": {
      "type": "string",
      "description": "Message body of the invite email"
    },
    "role": {
      "type": "string",
      "description": "Unique key of the role"
    },
    "groups": {
      "type": "array",
      "description": "Array of user group ids"
    },
    "email_address": {
      "type": "string",
      "description": "Email address  of the invited user"
    },
    "token": {
      "type": "string",
      "description": "Unique invite token"
    }
  },
  "required": [
    "email_address"
  ]
}
Responses201400
Headers
Content-Type: application/json
Body
{
  "language": "en",
  "subject": "Your invite is awaiting",
  "message": "Hi, <br />please join our community",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "groups": [
    1
  ],
  "email_address": "support@cmnty.com",
  "token": "cmnty348dfg3",
  "id": 123,
  "status": "accepted",
  "sent_count": 1,
  "self": "https://../api/user/invites/{id}",
  "groups_url": "https://../api/user/invites/{id}/groups",
  "accept_url": "https://../authorize/invite/cmnty348dfg3",
  "decline_url": "https://../authorize/decline/cmnty348dfg3",
  "created_at": "2017-02-28T09:39:33+00:00",
  "last_sent_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "subject": {
      "type": "string",
      "description": "Subject of the invite email"
    },
    "message": {
      "type": "string",
      "description": "Message body of the invite email"
    },
    "groups": {
      "type": "array",
      "description": "Array of user group ids"
    },
    "email_address": {
      "type": "string",
      "description": "Email address  of the invited user"
    },
    "token": {
      "type": "string",
      "description": "Unique invite token"
    },
    "id": {
      "type": "number"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "accepted",
        "declined",
        "open"
      ]
    },
    "sent_count": {
      "type": "number",
      "description": "Amount of times the invite was sent by the platform"
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific invite"
    },
    "groups_url": {
      "type": "string",
      "description": "Resource URL to retrieve groups for this specific invite"
    },
    "accept_url": {
      "type": "string"
    },
    "decline_url": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "description": "Time the invite has been created. ISO 8601 format."
    },
    "last_sent_at": {
      "type": "string",
      "description": "Time the invite has been sent for the last time. ISO 8601 format."
    }
  },
  "required": [
    "email_address"
  ]
}
Body
{
  "message": "Validation failed",
  "code": "VALIDATION-0001",
  "errors": {
    "email_address": [
      {
        "message": "This value should not be blank.",
        "code": "VALIDATION-0101"
      }
    ]
  }
}

Create new invite
POST/user/invites{?send-email}

Create a new invite.

Role defaults to member when not set.

Language, subject and message default to the default platform settings when not set.

URI Parameters
HideShow
send-email
boolean (optional) Default: 0 Example: 0

Defines that an email should be sent on creation of the invite. By default no email is being send, unless send-email paramater is: present but unset, 1 or true.


GET https://yourdomain/user/invites/1
Responses200404
Headers
Content-Type: application/json
Body
{
  "language": "en",
  "subject": "Your invite is awaiting",
  "message": "Hi, <br />please join our community",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "groups": [
    1
  ],
  "email_address": "support@cmnty.com",
  "token": "cmnty348dfg3",
  "id": 123,
  "status": "accepted",
  "sent_count": 1,
  "self": "https://../api/user/invites/{id}",
  "groups_url": "https://../api/user/invites/{id}/groups",
  "accept_url": "https://../authorize/invite/cmnty348dfg3",
  "decline_url": "https://../authorize/decline/cmnty348dfg3",
  "created_at": "2017-02-28T09:39:33+00:00",
  "last_sent_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "subject": {
      "type": "string",
      "description": "Subject of the invite email"
    },
    "message": {
      "type": "string",
      "description": "Message body of the invite email"
    },
    "groups": {
      "type": "array",
      "description": "Array of user group ids"
    },
    "email_address": {
      "type": "string",
      "description": "Email address  of the invited user"
    },
    "token": {
      "type": "string",
      "description": "Unique invite token"
    },
    "id": {
      "type": "number"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "accepted",
        "declined",
        "open"
      ]
    },
    "sent_count": {
      "type": "number",
      "description": "Amount of times the invite was sent by the platform"
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific invite"
    },
    "groups_url": {
      "type": "string",
      "description": "Resource URL to retrieve groups for this specific invite"
    },
    "accept_url": {
      "type": "string"
    },
    "decline_url": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "description": "Time the invite has been created. ISO 8601 format."
    },
    "last_sent_at": {
      "type": "string",
      "description": "Time the invite has been sent for the last time. ISO 8601 format."
    }
  },
  "required": [
    "email_address"
  ]
}
Body
{
  "code": "USER-0201",
  "message": "Invite does not exist"
}

Get invite
GET/user/invites/{id}

Retrieve a single invite by its unique ID.

URI Parameters
HideShow
id
number (required) Example: 1

The unique ID of the invite


PATCH https://yourdomain/user/invites/1
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "language": "en",
  "subject": "Your invite is awaiting",
  "message": "Hi, <br />please join our community",
  "role": "community-manager",
  "groups": [
    1
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "subject": {
      "type": "string",
      "description": "Subject of the invite email"
    },
    "message": {
      "type": "string",
      "description": "Message body of the invite email"
    },
    "role": {
      "type": "string",
      "description": "Unique key of the role"
    },
    "groups": {
      "type": "array",
      "description": "Array of user group ids"
    }
  }
}
Responses200403403404
Headers
Content-Type: application/json
Body
{
  "language": "en",
  "subject": "Your invite is awaiting",
  "message": "Hi, <br />please join our community",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "groups": [
    1
  ],
  "email_address": "support@cmnty.com",
  "token": "cmnty348dfg3",
  "id": 123,
  "status": "accepted",
  "sent_count": 1,
  "self": "https://../api/user/invites/{id}",
  "groups_url": "https://../api/user/invites/{id}/groups",
  "accept_url": "https://../authorize/invite/cmnty348dfg3",
  "decline_url": "https://../authorize/decline/cmnty348dfg3",
  "created_at": "2017-02-28T09:39:33+00:00",
  "last_sent_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "subject": {
      "type": "string",
      "description": "Subject of the invite email"
    },
    "message": {
      "type": "string",
      "description": "Message body of the invite email"
    },
    "groups": {
      "type": "array",
      "description": "Array of user group ids"
    },
    "email_address": {
      "type": "string",
      "description": "Email address  of the invited user"
    },
    "token": {
      "type": "string",
      "description": "Unique invite token"
    },
    "id": {
      "type": "number"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "accepted",
        "declined",
        "open"
      ]
    },
    "sent_count": {
      "type": "number",
      "description": "Amount of times the invite was sent by the platform"
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific invite"
    },
    "groups_url": {
      "type": "string",
      "description": "Resource URL to retrieve groups for this specific invite"
    },
    "accept_url": {
      "type": "string"
    },
    "decline_url": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "description": "Time the invite has been created. ISO 8601 format."
    },
    "last_sent_at": {
      "type": "string",
      "description": "Time the invite has been sent for the last time. ISO 8601 format."
    }
  },
  "required": [
    "email_address"
  ]
}
Body
{
  "code": "USER-0211",
  "message": "Invite is accepted"
}
Body
{
  "code": "USER-0212",
  "message": "Invite is declined"
}
Body
{
  "code": "USER-0201",
  "message": "Invite does not exist"
}

Update an invite
PATCH/user/invites/{id}

Update an existing invite.

Only open invites can be updated.

URI Parameters
HideShow
id
number (required) Example: 1

The unique ID of the invite


DELETE https://yourdomain/user/invites/1
Responses204403404
This response has no content.
Body
{
  "code": "USER-0211",
  "message": "Invite is accepted"
}
Body
{
  "code": "USER-0201",
  "message": "Invite does not exist"
}

Delete an invite
DELETE/user/invites/{id}

Delete a single invite from the platform. Accepted invites cannot be deleted.

URI Parameters
HideShow
id
number (required) Example: 1

The unique ID of the invite


POST https://yourdomain/user/invites/1/send
Responses204403403403404
This response has no content.
Body
{
  "code": "USER-0211",
  "message": "Invite is accepted"
}
Body
{
  "code": "USER-0212",
  "message": "Invite is declined"
}
Body
{
  "code": "USER-0213",
  "message": "Invite does not contain a valid email address"
}
Body
{
  "code": "USER-0201",
  "message": "Invite does not exist"

Send an invite
POST/user/invites/{id}/send

Send an existing invite to the email address.

URI Parameters
HideShow
id
number (required) Example: 1

The unique ID of the invite


GET https://yourdomain/user/invites/1/groups?offset=0&limit=10
Responses200404
Headers
Content-Type: application/json
Link: <https://../user/invites/{id}/groups>;rel="first", <https://../user/invites/{id}/groups>;rel="previous", <https://../user/invites>;rel="next", <https://../user/invites/{id}/groups>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "dynamic": false,
    "name": "age 20 to 40"
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Body
{
  "code": "USER-0201",
  "message": "Invite does not exist"
}

Get invite groups
GET/user/invites/{id}/groups{?offset,limit}

Retrieve the groups attached to an invite.

URI Parameters
HideShow
id
number (required) Example: 1

The unique ID of the invite

offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination


Users

GET https://yourdomain/user/users?offset=0&limit=10
Responses200
Headers
Content-Type: application/json
Link: <https://../user/users>;rel="first", <https://../user/users>;rel="previous", <https://../user/users>;rel="next", <https://../user/users>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "username": "jack",
    "email_address": "hello@example.org",
    "language": "en",
    "role": {
      "id": 123,
      "name": "Community Manager",
      "key": "community-manager"
    },
    "status": "active",
    "profile_url": "https://../user/profile/{id}/{username}",
    "avatar_url": "https://../avatar.png",
    "self": "https://../api/user/users/{id}",
    "created_at": "2017-02-28T09:39:33+00:00",
    "updated_at": "2017-02-28T09:39:33+00:00",
    "logged_in_at": "2017-02-28T09:39:33+00:00",
    "last_activity_at": "2017-02-28T09:39:33+00:00",
    "signed_off_at": "2017-02-28T09:39:33+00:00"
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get users
GET/user/users{?offset,limit}

Retrieve all users from the platform.

URI Parameters
HideShow
offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination

filter
array[string] (optional) Example: [status][]=active
  • status - To filter on the status of the user [ active | activation_pending | frozen | signed_off ]
sort
string (optional) Default: id Example: id,-created_at

The way the users are sorted. Use a minus sign (-) in front of the field to sort descending

  • id - To sort on the ID of the user

  • created_at - To sort on the creation date of the user


POST https://yourdomain/user/users
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "username": "jack",
  "password": "secret123",
  "email_address": "hello@example.org",
  "language": "en",
  "role": "community-manager",
  "groups": [
    4,
    5,
    9
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "role": {
      "type": "string",
      "description": "Unique key of the role"
    },
    "groups": {
      "type": "array",
      "description": "Ids of user groups"
    }
  }
}
Responses201400
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "username": "jack",
  "email_address": "hello@example.org",
  "language": "en",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "status": "active",
  "profile_url": "https://../user/profile/{id}/{username}",
  "avatar_url": "https://../avatar.png",
  "self": "https://../api/user/users/{id}",
  "created_at": "2017-02-28T09:39:33+00:00",
  "updated_at": "2017-02-28T09:39:33+00:00",
  "logged_in_at": "2017-02-28T09:39:33+00:00",
  "last_activity_at": "2017-02-28T09:39:33+00:00",
  "signed_off_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "username": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "activation_pending",
        "frozen",
        "signed_off"
      ]
    },
    "profile_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "avatar_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific user."
    },
    "created_at": {
      "type": "string",
      "description": "Time the user has been created. ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "description": "Time the user has been updated. ISO 8601 format."
    },
    "logged_in_at": {
      "type": "string",
      "description": "Time the user logged in for the last time. ISO 8601 format."
    },
    "last_activity_at": {
      "type": "string",
      "description": "Time the user was last active. ISO 8601 format."
    },
    "signed_off_at": {
      "type": "string",
      "description": "Date the user signed off. ISO 8601 format."
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "message": "Validation failed",
  "code": "VALIDATION-0001",
  "errors": {
    "email_address": [
      {
        "message": "This value should not be blank.",
        "code": "VALIDATION-0101"
      }
    ]
  }
}

Create new user
POST/user/users

Create a new user.

Role defaults to member when not set.

Language default to the default platform language when not set.


PATCH https://yourdomain/user/users/1
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "email_address": "hello@example.org",
  "language": "en",
  "role": "community-manager",
  "groups": [
    4,
    5,
    9
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string",
      "description": "Language string"
    },
    "role": {
      "type": "string",
      "description": "Unique key of the role"
    },
    "groups": {
      "type": "array",
      "description": "Ids of user groups"
    }
  }
}
Responses201400409
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "username": "jack",
  "email_address": "hello@example.org",
  "language": "en",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "status": "active",
  "profile_url": "https://../user/profile/{id}/{username}",
  "avatar_url": "https://../avatar.png",
  "self": "https://../api/user/users/{id}",
  "created_at": "2017-02-28T09:39:33+00:00",
  "updated_at": "2017-02-28T09:39:33+00:00",
  "logged_in_at": "2017-02-28T09:39:33+00:00",
  "last_activity_at": "2017-02-28T09:39:33+00:00",
  "signed_off_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "username": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "activation_pending",
        "frozen",
        "signed_off"
      ]
    },
    "profile_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "avatar_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific user."
    },
    "created_at": {
      "type": "string",
      "description": "Time the user has been created. ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "description": "Time the user has been updated. ISO 8601 format."
    },
    "logged_in_at": {
      "type": "string",
      "description": "Time the user logged in for the last time. ISO 8601 format."
    },
    "last_activity_at": {
      "type": "string",
      "description": "Time the user was last active. ISO 8601 format."
    },
    "signed_off_at": {
      "type": "string",
      "description": "Date the user signed off. ISO 8601 format."
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "message": "Validation failed",
  "code": "VALIDATION-0001",
  "errors": {
    "email_address": [
      {
        "message": "This value should not be blank.",
        "code": "VALIDATION-0101"
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Update user
PATCH/user/users/{id}

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user


GET https://yourdomain/user/users/1
Responses200404409
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "username": "jack",
  "email_address": "hello@example.org",
  "language": "en",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "status": "active",
  "profile_url": "https://../user/profile/{id}/{username}",
  "avatar_url": "https://../avatar.png",
  "self": "https://../api/user/users/{id}",
  "created_at": "2017-02-28T09:39:33+00:00",
  "updated_at": "2017-02-28T09:39:33+00:00",
  "logged_in_at": "2017-02-28T09:39:33+00:00",
  "last_activity_at": "2017-02-28T09:39:33+00:00",
  "signed_off_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "username": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "activation_pending",
        "frozen",
        "signed_off"
      ]
    },
    "profile_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "avatar_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific user."
    },
    "created_at": {
      "type": "string",
      "description": "Time the user has been created. ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "description": "Time the user has been updated. ISO 8601 format."
    },
    "logged_in_at": {
      "type": "string",
      "description": "Time the user logged in for the last time. ISO 8601 format."
    },
    "last_activity_at": {
      "type": "string",
      "description": "Time the user was last active. ISO 8601 format."
    },
    "signed_off_at": {
      "type": "string",
      "description": "Date the user signed off. ISO 8601 format."
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Get user
GET/user/users/{id}

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user


DELETE https://yourdomain/user/users/1?keep-content=1
Responses204404409
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Delete a user
DELETE/user/users/{id}{?keep-content}

Delete a single user from the platform. Platform Owner cannot be deleted.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user

keep-content
boolean (optional) Default: 1 Example: 1

Defines that content should be kept when deleting a user. By default content of the user is deleted, unless keep-content parameter is: present but unset, 1 or true.


POST https://yourdomain/user/users/1/freeze
Responses200404409
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "username": "jack",
  "email_address": "hello@example.org",
  "language": "en",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "status": "active",
  "profile_url": "https://../user/profile/{id}/{username}",
  "avatar_url": "https://../avatar.png",
  "self": "https://../api/user/users/{id}",
  "created_at": "2017-02-28T09:39:33+00:00",
  "updated_at": "2017-02-28T09:39:33+00:00",
  "logged_in_at": "2017-02-28T09:39:33+00:00",
  "last_activity_at": "2017-02-28T09:39:33+00:00",
  "signed_off_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "username": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "activation_pending",
        "frozen",
        "signed_off"
      ]
    },
    "profile_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "avatar_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific user."
    },
    "created_at": {
      "type": "string",
      "description": "Time the user has been created. ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "description": "Time the user has been updated. ISO 8601 format."
    },
    "logged_in_at": {
      "type": "string",
      "description": "Time the user logged in for the last time. ISO 8601 format."
    },
    "last_activity_at": {
      "type": "string",
      "description": "Time the user was last active. ISO 8601 format."
    },
    "signed_off_at": {
      "type": "string",
      "description": "Date the user signed off. ISO 8601 format."
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Freeze a user
POST/user/users/{id}/freeze

Freeze a user by its unique ID or email address.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user


POST https://yourdomain/user/users/1/activate
Responses200404409
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "username": "jack",
  "email_address": "hello@example.org",
  "language": "en",
  "role": {
    "id": 123,
    "name": "Community Manager",
    "key": "community-manager"
  },
  "status": "active",
  "profile_url": "https://../user/profile/{id}/{username}",
  "avatar_url": "https://../avatar.png",
  "self": "https://../api/user/users/{id}",
  "created_at": "2017-02-28T09:39:33+00:00",
  "updated_at": "2017-02-28T09:39:33+00:00",
  "logged_in_at": "2017-02-28T09:39:33+00:00",
  "last_activity_at": "2017-02-28T09:39:33+00:00",
  "signed_off_at": "2017-02-28T09:39:33+00:00"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "username": {
      "type": "string"
    },
    "email_address": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "Unique identifier of the role"
        },
        "name": {
          "type": "string",
          "description": "Name of the role"
        },
        "key": {
          "type": "string",
          "description": "Unique key of the role"
        }
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "activation_pending",
        "frozen",
        "signed_off"
      ]
    },
    "profile_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "avatar_url": {
      "type": "string",
      "description": "Resource URL to the avatar of the specific user."
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific user."
    },
    "created_at": {
      "type": "string",
      "description": "Time the user has been created. ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "description": "Time the user has been updated. ISO 8601 format."
    },
    "logged_in_at": {
      "type": "string",
      "description": "Time the user logged in for the last time. ISO 8601 format."
    },
    "last_activity_at": {
      "type": "string",
      "description": "Time the user was last active. ISO 8601 format."
    },
    "signed_off_at": {
      "type": "string",
      "description": "Date the user signed off. ISO 8601 format."
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Activate a user
POST/user/users/{id}/activate

Activate a user by its unique ID or email address.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user


GET https://yourdomain/user/users/1/groups?offset=0&limit=10
Responses200404409
Headers
Content-Type: application/json
Link: <https://../user/users/{id}/groups>;rel="first", <https://../user/users/{id}/groups>;rel="previous", <https://../user/users/{id}/groups>;rel="next", <https://../user/users/{id}/groups>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "dynamic": false,
    "name": "age 20 to 40"
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Get user groups
GET/user/users/{id}/groups{?offset,limit}

Retrieve the groups attached to a user.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user

offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination


GET https://yourdomain/user/users/1/points
Responses200404409
Headers
Content-Type: application/json
Body
{
  "total": 150,
  "remaining": 50
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Get user points
GET/user/users/{id}/points

Retrieve the earned and the remaining points for a user.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user


POST https://yourdomain/user/users/1/points
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "amount": 10,
  "reason": "For being an awesome member"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "description": "Amount of points rewarded"
    },
    "reason": {
      "type": "string",
      "description": "Reason for rewarding points"
    }
  },
  "required": [
    "amount"
  ]
}
Responses201400404409
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "amount": 10,
  "reason": "For being an awesome member",
  "type": "manual"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "amount": {
      "type": "number",
      "description": "Amount of points rewarded"
    },
    "reason": {
      "type": "string",
      "description": "Reason for rewarding points"
    },
    "type": {
      "type": "string",
      "enum": [
        "manual",
        "auto"
      ]
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "message": "Validation failed",
  "code": "VALIDATION-0001",
  "errors": {
    "amount": [
      {
        "message": "This value should not be blank.",
        "code": "VALIDATION-0101"
      }
    ]
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Reward points to a user
POST/user/users/{id}/points

Manually reward points to a user.

The amount of points to reward is required. When a negative value is used, points will be deducted.

The reason for rewarding the points is optional.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user


GET https://yourdomain/user/users/1/points/history?offset=0&limit=10
Responses200404409
Headers
Content-Type: application/json
Link: <https://../user/users/{id}/points/history>;rel="first", <https://../user/users/{id}/points/history>;rel="previous", <https://../user/users/{id}/points/history>;rel="next", <https://../user/users/{id}/points/history>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "amount": 10,
    "reason": "For being an awesome member",
    "type": "manual"
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Get user points history
GET/user/users/{id}/points/history{?offset,limit}

Retrieve the points that were awarded to a user.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user

offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination


GET https://yourdomain/user/users/1/badges?offset=0&limit=10
Responses200404409
Headers
Content-Type: application/json
Link: <https://../user/users/{id}/badges>;rel="first", <https://../user/users/{id}/badges>;rel="previous", <https://../user/users/{id}/badges>;rel="next", <https://../user/users/{id}/badges>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "type": "manual",
    "name": "Active commentator",
    "description": "For commenting on content",
    "level": {
      "id": 123,
      "name": "Silver"
    }
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Get user badges
GET/user/users/{id}/badges{?offset,limit}

Retrieve current set of badges awarded to a user.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user

offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination


GET https://yourdomain/user/users/1/badges/history?offset=0&limit=10
Responses200404409
Headers
Content-Type: application/json
Link: <https://../user/users/{id}/badges/history>;rel="first", <https://../user/users/{id}/badges/history>;rel="previous", <https://../user/users/{id}/badges/history>;rel="next", <https://../user/users/{id}/badges/history>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "received_at": "2017-02-28T09:39:33+00:00",
    "badge": {
      "id": 123,
      "type": "manual",
      "name": "Active commentator",
      "description": "For commenting on content",
      "level": {
        "id": 123,
        "name": "Silver"
      }
    }
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0101",
  "message": "User does not exist"
}
Headers
Content-Type: application/json
Body
{
  "message": "Multiple records have been found with the supplied email address. Use the ID instead.",
  "code": "USER-0103"
}

Get user badge history
GET/user/users/{id}/badges/history{?offset,limit}

Retrieve the history of badges awarded to a user.

URI Parameters
HideShow
id
number|string (required) Example: 1

The unique ID or email address of the user

offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination


Groups

GET https://yourdomain/user/groups?offset=0&limit=10
Responses200
Headers
Content-Type: application/json
Link: <https://../user/groups>;rel="first", <https://../user/groups>;rel="previous", <https://../user/groups>;rel="next", <https://../user/groups>;rel="last"
X-Total-Count: 12
Body
[
  {
    "id": 123,
    "dynamic": false,
    "name": "age 20 to 40",
    "self": "https://../api/user/groups/{id}"
  }
]
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get groups
GET/user/groups{?offset,limit}

Retrieve all groups from the platform.

URI Parameters
HideShow
offset
number (optional) Default: 0 Example: 0

The offset for pagination

limit
number (optional) Default: 10 Example: 10

The limit for pagination


GET https://yourdomain/user/groups/1
Responses200404
Headers
Content-Type: application/json
Body
{
  "id": 123,
  "dynamic": false,
  "name": "age 20 to 40",
  "self": "https://../api/user/groups/{id}"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "dynamic": {
      "type": "boolean",
      "description": "Whether or not it's a dynamic group"
    },
    "name": {
      "type": "string",
      "description": "Name of the group"
    },
    "self": {
      "type": "string",
      "description": "Resource URL to retrieve this specific group."
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "code": "USER-0301",
  "message": "Group does not exist"
}

Get group by id
GET/user/groups/{id}

URI Parameters
HideShow
id
number (required) Example: 1

The unique ID of the group


Generated by CMNTY on 01 Oct 2018