Recommendations

List Recommendations

List all recommendations that you have access to.

Request

GET /organizations/<organization_id>/recommendations

Filtering

The filter parameter has the following format: key::value. You can combine keys for stricter searches, e.g. state::active|query::archery.

Results can be filtered with the following keys:

Sorting

The sort parameter has the following format: key1|key2. You can optionally include a - to indicate descending order. e.g. -title would return results in reverse-alphabetical order.

Results can be sorted with the following keys:

Paging

At most 50 results are returned at a time. Include an optional page parameter to fetch the next page of results.

Response

200 OK

{
  "data": [
    {
      "id": "941e9d86-43fe-4f18-b463-e42d1bca719c",
      "title": "Another Badge",
      "type": "badge",
      "recommended_badge_template_id": "cf9bdf2c-ffcc-4de1-9f35-8be3871410b6",
      "updated_at": "2019-06-26T07:27:53.629Z",
      "badge_templates_count": 0
    },
    {
      "id": "4b8b2c97-b61b-4db1-8a65-8f176d080a1e",
      "title": "My First Badge",
      "type": "badge",
      "recommended_badge_template_id": "44833497-e12a-44e0-9675-dd4cce8052c4",
      "updated_at": "2019-06-26T07:27:53.614Z",
      "badge_templates_count": 1
    },
    {
      "id": "192e74d7-f002-4ec8-9111-a920e57fe9c3",
      "title": "Recommendation Title",
      "type": "information",
      "activity_url": "http://www.lolcats.com",
      "updated_at": "2019-06-26T07:27:53.633Z",
      "badge_templates_count": 0
    }
  ],
  "metadata": {
    "count": 3,
    "current_page": 1,
    "total_count": 3,
    "total_pages": 1,
    "per": 50,
    "previous_page_url": null,
    "next_page_url": null
  }
}

Recommendation Details

Request details for a single recommendation

Request

GET /organizations/<organization_id>/recommendations/<recommendation_id>

Response

200 OK

{
  "data": {
    "id": "331f40b1-71f8-403a-994e-800dbbf76840",
    "title": "My First Badge",
    "type": "badge",
    "activity_url": "",
    "recommended_badge_template_id": "bd48639a-107c-4074-9364-a559af62f0ce",
    "url": "/org/acclaim/badge/my-first-badge",
    "issuer_name": "Acclaim",
    "image_url": null,
    "issuer_icon": null,
    "description": "Dynamically deliver go forward e-tailers",
    "badge_template_ids": [
      "cdc0a99b-d4c3-4ecc-a4f1-b4968edb5b0d"
    ]
  },
  "metadata": {
  }
}

List Badge Templates

List Badge Templates that link to a Recommendation

Request

GET /organizations/<organization_id>/recommendations/<recommendation_id>/badge_templates

Query parameters, input and output are identical to the Badge Template list endpoint. See Badge Templates.

Response

200 OK

{
  "data": [
    {
      "id": "00bc7d59-4c6a-4765-9414-8d2709760671",
      "image_url": null,
      "name": "Another Badge",
      "public": true,
      "updated_at": "2019-06-24T18:38:02.583Z",
      "owner": {
        "id": "e67ebfdb-e23f-5789-a31d-6c5668bb09b8",
        "name": "Acclaim"
      }
    }
  ],
  "metadata": {
    "count": 1,
    "current_page": 1,
    "total_count": 1,
    "total_pages": 1,
    "per": 50,
    "previous_page_url": null,
    "next_page_url": null
  }
}

Create Badge Recommendation

Create a new recommendation for a Badge Template.

Request

POST /organizations/<organization_id>/recommendations

Request Body

{
  "type": "badge",
  "recommended_badge_template_id": "8bc4ad34-d05d-4222-8c42-bd035ba12f14",
  "badge_template_ids": [
    "72f0e84a-92a9-45cf-972d-c87183733a17"
  ]
}

Response

201 Created

{
  "data": {
    "id": "30c100f3-2d4a-4108-9619-bf7d3d86ac8b",
    "title": "My Badge",
    "type": "badge",
    "activity_url": "",
    "recommended_badge_template_id": "8bc4ad34-d05d-4222-8c42-bd035ba12f14",
    "url": "/org/acclaim/badge/my-badge",
    "issuer_name": "Acclaim",
    "image_url": null,
    "issuer_icon": null,
    "description": "Dynamically deliver go forward e-tailers",
    "badge_template_ids": [
      "72f0e84a-92a9-45cf-972d-c87183733a17"
    ]
  },
  "metadata": {
  }
}

Create URL Recommendation

Create a new recommendation for a URL.

Request

POST /organizations/<organization_id>/recommendations

Request Body

{
  "title": "Go to this URL",
  "description": "This is a wonderful URL",
  "type": "information",
  "activity_url": "http://example.com",
  "badge_template_ids": [
    "c70dbdcc-e0ca-4a29-b510-541e6a539825"
  ]
}

Response

201 Created

{
  "data": {
    "id": "48abd7a8-9f12-4675-89cd-bd706c1a7c63",
    "title": "Go to this URL immediately!",
    "type": "information",
    "activity_url": "http://www.example.com",
    "recommended_badge_template_id": null,
    "url": "http://www.example.com",
    "issuer_name": "Acclaim",
    "image_url": null,
    "issuer_icon": null,
    "description": "This is a very important URL.",
    "badge_template_ids": [
      "c70dbdcc-e0ca-4a29-b510-541e6a539825"
    ]
  },
  "metadata": {
  }
}

Update an Existing Recommendation

This endpoint is identical to Create, except that a current id should be passed in with the request.

Request

PATCH /organizations/<organization_id>/recommendations/<recommendation_id>

Request Body

{
  "id": "2e9214fc-f455-4403-b3d8-445392e89417",
  ...
}

Response

200 OK

{
  "data": {
    "id": "7261444c-3188-4d2a-95d1-795fe8348d8f",
    "title": "My First Badge",
    "type": "badge",
    "activity_url": "",
    "recommended_badge_template_id": "1b4eeacc-525d-41a5-9fec-c32fc458ea53",
    "url": "/org/acclaim/badge/my-first-badge",
    "issuer_name": "Acclaim",
    "image_url": null,
    "issuer_icon": null,
    "description": "Dynamically deliver go forward e-tailers",
    "badge_template_ids": [
      "1401d909-7564-48b2-9809-fcbbcbfbe7fd"
    ]
  },
  "metadata": {
  }
}

Delete a Recommendation

Delete an existing recommendation.

Request

DELETE /organizations/<organization_id>/recommendations/<recommendation_id>

Response

204 No Content