Skip to content

Issue a Badge

Issue a Badge

Please note that an archived badge template cannot be used to issue new badges. When issuing a badge, a user_id can also be specified. When a user_id is specified, the badge will be associated with the user_id and the notification will be sent to the specified recipient_email. Using the endpoint in this way, you may issue badges to users whose email addresses have changed.

Duplicate badges cannot be issued. They are defined as a badge using the same badge template, the same recipient_email, and either the same issued_at or expires_at timestamp as a previously existing badge.

Required Fields

  • recipient_email
  • issued_to_first_name
  • issued_to_last_name
  • badge_template_id
  • issued_at

Optional Fields

  • issuer_earner_id allows you to attach your own system's user ID to a badge for recordkeeping. The issuer_earner_id will be returned in API calls and in reports, but it will not be shown to the user on the Acclaim site. Default: null
  • locale allows you to define the language badge notification emails will be sent in. Available locales include: "en", "fr", "de", "ko", "ja", "zh-CN", "pt", "es-ES", "es-US". Default: "en"
  • suppress_badge_notification_email prevents Acclaim from sending notification or reminder emails to the user about this badge. This allows you to send your own badge notification to the user without sending a duplicate email. Default: false.
  • expires_at
  • evidence

Request

POST /organizations/<organization_id>/badges

Request Body

{
  "recipient_email": "test@example.com",
  "user_id": "95787b46-352d-4d04-a27d-bf1d0cd9c5c6",
  "badge_template_id": "cfaf2910-ea5f-46f1-89a5-db525dad6e58",
  "issued_at": "2014-04-01 09:41:00 -0500",
  "issued_to_first_name": "Earner First Name",
  "issued_to_last_name": "Earner Last Name",
  "expires_at": null,
  "issuer_earner_id": "abc123",
  "locale": "en",
  "suppress_badge_notification_email": false
}

Response

201 Created Location: <badge_url>

{
  "data": {
    "user": {
      "id": "b21ef30f-ab30-48fa-8dcd-cf79cc0b6cc4",
      "email": "b21ef30f-ab30-48fa-8dcd-cf79cc0b6cc4@example.com",
      "first_name": "Alfred",
      "last_name": "Skiles",
      "current_position_name": "*****",
      "current_organization_name": "*****",
      "confirmed": true,
      "photo": null,
      "photo_url": null,
      "url": "https://localhost/user/alfred-skiles"
    },
    "printing_enabled": false,
    "issuer": {
      "type": "Organization",
      "id": "c616a632-f9ed-4453-be90-bef20e8eb06c",
      "name": "Organization 4",
      "url": "https://api.youracclaim.com/v1/organizations/c616a632-f9ed-4453-be90-bef20e8eb06c",
      "vanity_url": "https://localhost/org/organization-4",
      "verified": true
    },
    "badge_template": {
      "id": "66c1cf3f-5b98-4f90-a83c-eac0c2e5809c",
      "description": "Dynamically deliver go forward e-tailers",
      "global_activity_url": "https://www.example.com/foo",
      "name": "Badge Template 2",
      "state": "active",
      "public": true,
      "badges_count": 1,
      "recipient_type": "User",
      "show_badge_lmi": false,
      "show_lmi_jobs": false,
      "show_skill_tag_links": true,
      "vanity_slug": "badge-template-2",
      "criteria_url_name": null,
      "criteria_url": null,
      "certification": true,
      "state_updated_at": null,
      "created_at": "2014-04-01T14:41:00.000Z",
      "updated_at": "2014-04-01T14:41:00.000Z",
      "template_type": "skill",
      "show_template_settings": false,
      "get_issue_count": 1,
      "image": {
        "id": "fc9b44fd-59c4-4ef7-b983-4bf1cbd7b8b9",
        "url": "/system/test/images/fc9b44fd-59c4-4ef7-b983-4bf1cbd7b8b9/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "url": "https://localhost/org/organization-4/badge/badge-template-2",
      "owner": {
        "type": "Organization",
        "id": "c616a632-f9ed-4453-be90-bef20e8eb06c",
        "name": "Organization 4",
        "url": "https://api.youracclaim.com/v1/organizations/c616a632-f9ed-4453-be90-bef20e8eb06c",
        "vanity_url": "https://localhost/org/organization-4",
        "vanity_slug": "organization-4",
        "verified": true,
        "viewable": true
      },
      "alignments": [
        {
          "id": "ce1dbea1-0ed1-44c0-af57-417a0e083cb6",
          "name": "Alignment 2",
          "url": "http://www.example.com/alignment",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "recommendations": [
        {
          "id": "d703d433-9972-4a32-bdb8-db955f4cd9d4",
          "title": "Go to this URL immediately!",
          "type": "url",
          "activity_url": "http://www.example.com/recommendation"
        }
      ],
      "required_badge_templates": [

      ],
      "badge_template_activities": [
        {
          "id": "300de7b4-08c4-4214-a6d6-5536d9827eba",
          "title": "Kickboxing Activity",
          "activity_type": "Schedule / Registration",
          "activity_url": "http://www.example.com/awesomepage",
          "required_badge_template_id": null
        }
      ],
      "skills": [
        "Skill 2"
      ]
    },
    "id": "f77311e5-9d8c-4c4f-a5e7-089ae2f0b85b",
    "issued_to": "Earner First Name Earner Last Name",
    "issued_to_first_name": "Earner First Name",
    "issued_to_last_name": "Earner Last Name",
    "issuer_earner_id": "abc123",
    "locale": "en",
    "public": true,
    "recipient_email": "test@example.com",
    "replacement_badge_id": null,
    "revocation_reason": null,
    "state": "pending",
    "suppress_badge_notification_email": false,
    "created_at": "2014-04-01T14:41:00.000Z",
    "expires_at": null,
    "expires_at_date": null,
    "issued_at": "2014-04-01T14:41:00.000Z",
    "issued_at_date": "2014-04-01",
    "state_updated_at": null,
    "image": {
      "id": "fc9b44fd-59c4-4ef7-b983-4bf1cbd7b8b9",
      "url": "/system/test/images/fc9b44fd-59c4-4ef7-b983-4bf1cbd7b8b9/fake-352x352.png"
    },
    "image_url": "https://cdn.example.com/path/to/image.png",
    "alignments": [
      {
        "name": "Alignment 2",
        "description": "Self-enabling cohesive task-force"
      }
    ],
    "evidence": [

    ],
    "accept_badge_url": "https://localhost/badges/f77311e5-9d8c-4c4f-a5e7-089ae2f0b85b/accept"
  },
  "metadata": {
  }
}

Badge Evidence

A Badge can have multiple items of evidence associated with it. The three evidence types are KeyValueGroupEvidence, PlainTextEvidence and UrlEvidence. Here is an example of creating a badge with all three types:

Request Body

{
  "recipient_email": "test@example.com",
  "badge_template_id": "63f87fa1-f7e5-4925-981d-54ec312df1ec",
  "issued_at": "2014-04-01 09:41:00 -0500",
  "issued_to": "Firstname Lastname",
  "issued_to_first_name": "Firstname",
  "issued_to_last_name": "Lastname",
  "expires_at": null,
  "evidence": [
    {
      "type": "KeyValueGroupEvidence",
      "name": "Custom Evidence",
      "values": [
        {
          "type": "KeyValuePairEvidence",
          "key": "Testing Center",
          "value": "Master Test Facility, Minneapolis, MN",
          "url": "http://www.url-in-custom-evidence-is-optional.com"
        }
      ]
    },
    {
      "type": "PlainTextEvidence",
      "title": "Evidence",
      "description": "The evidence is clear."
    },
    {
      "type": "UrlEvidence",
      "value": "http://www.example.com/evidence",
      "description": "Description in URL evidence is optional",
      "name": "Evidence"
    }
  ]
}

Response

201 Created Location: <badge_url>

{
  "data": {
    "user": {
    },
    "printing_enabled": false,
    "issuer": {
      "type": "Organization",
      "id": "0d66f168-19d4-4054-bb3f-9299de2c7129",
      "name": "Organization 1",
      "url": "https://api.youracclaim.com/v1/organizations/0d66f168-19d4-4054-bb3f-9299de2c7129",
      "vanity_url": "https://localhost/org/organization-1",
      "verified": true
    },
    "badge_template": {
      "id": "98326bf4-7d61-4630-a4d2-0b813d6a0fdf",
      "description": "Dynamically deliver go forward e-tailers",
      "global_activity_url": "https://www.example.com/foo",
      "name": "Badge Template 1",
      "state": "active",
      "public": true,
      "badges_count": 1,
      "recipient_type": "User",
      "show_badge_lmi": false,
      "show_lmi_jobs": false,
      "show_skill_tag_links": true,
      "vanity_slug": "badge-template-1",
      "criteria_url_name": null,
      "criteria_url": null,
      "certification": true,
      "state_updated_at": null,
      "created_at": "2014-04-01T14:41:00.000Z",
      "updated_at": "2014-04-01T14:41:00.000Z",
      "template_type": "skill",
      "show_template_settings": false,
      "get_issue_count": 1,
      "image": {
        "id": "9024300c-5dec-4025-b770-1e0f1a42f6d0",
        "url": "/system/test/images/9024300c-5dec-4025-b770-1e0f1a42f6d0/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "url": "https://localhost/org/organization-1/badge/badge-template-1",
      "owner": {
        "type": "Organization",
        "id": "0d66f168-19d4-4054-bb3f-9299de2c7129",
        "name": "Organization 1",
        "url": "https://api.youracclaim.com/v1/organizations/0d66f168-19d4-4054-bb3f-9299de2c7129",
        "vanity_url": "https://localhost/org/organization-1",
        "vanity_slug": "organization-1",
        "verified": true,
        "viewable": true
      },
      "alignments": [
        {
          "id": "fc014f42-1219-4272-8538-60c72e12359b",
          "name": "Alignment 1",
          "url": "http://www.example.com/alignment",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "recommendations": [
        {
          "id": "60b9586d-8eea-404d-91ef-d1a1c27a1755",
          "title": "Go to this URL immediately!",
          "type": "url",
          "activity_url": "http://www.example.com/recommendation"
        }
      ],
      "required_badge_templates": [

      ],
      "badge_template_activities": [
        {
          "id": "53929c8a-8e67-43a3-9dd9-1603670188b4",
          "title": "Kickboxing Activity",
          "activity_type": "Schedule / Registration",
          "activity_url": "http://www.example.com/awesomepage",
          "required_badge_template_id": null
        }
      ],
      "skills": [
        "Skill 1"
      ]
    },
    "id": "072ece01-153a-4b47-b75c-be97edcc079f",
    "issued_to": "Firstname Lastname",
    "issued_to_first_name": "Firstname",
    "issued_to_last_name": "Lastname",
    "issuer_earner_id": null,
    "locale": "en",
    "public": true,
    "recipient_email": "test@example.com",
    "replacement_badge_id": null,
    "revocation_reason": null,
    "state": "pending",
    "suppress_badge_notification_email": false,
    "created_at": "2014-04-01T14:41:00.000Z",
    "expires_at": null,
    "expires_at_date": null,
    "issued_at": "2014-04-01T14:41:00.000Z",
    "issued_at_date": "2014-04-01",
    "state_updated_at": null,
    "image": {
      "id": "9024300c-5dec-4025-b770-1e0f1a42f6d0",
      "url": "/system/test/images/9024300c-5dec-4025-b770-1e0f1a42f6d0/fake-352x352.png"
    },
    "image_url": "https://cdn.example.com/path/to/image.png",
    "alignments": [
      {
        "name": "Alignment 1",
        "description": "Self-enabling cohesive task-force"
      }
    ],
    "evidence": [
      {
        "id": "4dac9d91-2fd1-431a-a442-78a72f837a0b",
        "type": "KeyValueGroupEvidence",
        "name": "Custom Evidence",
        "values": [
          {
            "key": "Testing Center",
            "value": "Master Test Facility, Minneapolis, MN",
            "url": "http://www.url-in-custom-evidence-is-optional.com"
          }
        ]
      },
      {
        "id": "241453f0-2c54-489a-9050-2a088c24bbe8",
        "type": "PlainTextEvidence",
        "title": "Evidence",
        "description": "The evidence is clear."
      },
      {
        "id": "f0e3532c-82b0-4523-9281-5ae656963e48",
        "type": "UrlEvidence",
        "name": "Evidence",
        "description": "Description in URL evidence is optional",
        "value": "http://www.example.com/evidence"
      }
    ],
    "accept_badge_url": "https://localhost/badges/072ece01-153a-4b47-b75c-be97edcc079f/accept"
  },
  "metadata": {
  }
}

Issue a Batch of Badges

If one of the badges in the batch is invalid, an error will be returned including the index of the invalid badge. When issuing a badge, a recipient_email is required. A user_id can also be specified. When both recipient_email and user_id are specified, the badge will be associated with the user_id and the notification will be sent to the specified recipient_email. Using the endpoint in this way can allow badges to be issued to users whose email addresses have changed.

Request

POST /organizations/<organization_id>/badges/batch

Request Body

{
  "badges": [
    {
      "user_id": "36d5ebfb-1d4f-4488-97bc-e7871cff49ca",
      "recipient_email": "user971@example.com",
      "badge_template_id": "6c32280e-eb8c-4f9a-89c2-2dc3ac7c1861",
      "issued_at": "2014-04-01 09:41:00 -0500",
      "issued_to_first_name": "Alfred",
      "issued_to_last_name": "Skiles",
      "expires_at": null
    },
    {
      "user_id": "e614fef6-8461-4e0c-b94a-b493a202ec6e",
      "recipient_email": "user972@example.com",
      "badge_template_id": "6c32280e-eb8c-4f9a-89c2-2dc3ac7c1861",
      "issued_at": "2014-04-01 09:41:00 -0500",
      "issued_to_first_name": "Alfred",
      "issued_to_last_name": "Skiles",
      "expires_at": null
    }
  ]
}

Success Response

201 Created

{
  "data": [
    {
      "user": {
        "id": "3173fc14-ef1a-4df3-9856-a6397c7db331",
        "email": "3173fc14-ef1a-4df3-9856-a6397c7db331@example.com",
        "first_name": "Alfred",
        "last_name": "Skiles",
        "current_position_name": "*****",
        "current_organization_name": "*****",
        "confirmed": true,
        "photo": null,
        "photo_url": null,
        "url": "https://localhost/user/alfred-skiles"
      },
      "printing_enabled": false,
      "issuer": {
        "type": "Organization",
        "id": "ef04c4d3-de56-489f-bfab-79292f82f2dc",
        "name": "Organization 10",
        "url": "https://api.youracclaim.com/v1/organizations/ef04c4d3-de56-489f-bfab-79292f82f2dc",
        "vanity_url": "https://localhost/org/organization-10",
        "verified": true
      },
      "badge_template": {
        "id": "ffc28f60-d525-43de-94f7-715c697f69c2",
        "description": "Dynamically deliver go forward e-tailers",
        "global_activity_url": "https://www.example.com/foo",
        "name": "Badge Template 5",
        "state": "active",
        "public": true,
        "badges_count": 1,
        "recipient_type": "User",
        "show_badge_lmi": false,
        "show_lmi_jobs": false,
        "show_skill_tag_links": true,
        "vanity_slug": "badge-template-5",
        "criteria_url_name": null,
        "criteria_url": null,
        "certification": true,
        "state_updated_at": null,
        "created_at": "2014-04-01T14:41:00.000Z",
        "updated_at": "2014-04-01T14:41:00.000Z",
        "template_type": "skill",
        "show_template_settings": false,
        "get_issue_count": 1,
        "image": {
          "id": "fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba",
          "url": "/system/test/images/fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba/fake-352x352.png"
        },
        "image_url": "https://cdn.example.com/path/to/image.png",
        "url": "https://localhost/org/organization-10/badge/badge-template-5",
        "owner": {
          "type": "Organization",
          "id": "ef04c4d3-de56-489f-bfab-79292f82f2dc",
          "name": "Organization 10",
          "url": "https://api.youracclaim.com/v1/organizations/ef04c4d3-de56-489f-bfab-79292f82f2dc",
          "vanity_url": "https://localhost/org/organization-10",
          "vanity_slug": "organization-10",
          "verified": true,
          "viewable": true
        },
        "alignments": [
          {
            "id": "2641cc39-478e-4032-8dee-e3dcfcc86e12",
            "name": "Alignment 5",
            "url": "http://www.example.com/alignment",
            "description": "Self-enabling cohesive task-force"
          }
        ],
        "recommendations": [
          {
            "id": "5392e710-b410-4958-b046-8598fb22212e",
            "title": "Go to this URL immediately!",
            "type": "url",
            "activity_url": "http://www.example.com/recommendation"
          }
        ],
        "required_badge_templates": [

        ],
        "badge_template_activities": [
          {
            "id": "b544b81b-64b1-4900-b464-7f042d89323d",
            "title": "Kickboxing Activity",
            "activity_type": "Schedule / Registration",
            "activity_url": "http://www.example.com/awesomepage",
            "required_badge_template_id": null
          }
        ],
        "skills": [
          "Skill 5"
        ]
      },
      "id": "1b06d9ad-f2d9-44e9-8bf2-86b7785ef473",
      "issued_to": "Alfred Skiles",
      "issued_to_first_name": "Alfred",
      "issued_to_last_name": "Skiles",
      "issuer_earner_id": null,
      "locale": "en",
      "public": true,
      "recipient_email": "user6@example.com",
      "replacement_badge_id": null,
      "revocation_reason": null,
      "state": "pending",
      "suppress_badge_notification_email": false,
      "created_at": "2014-04-01T14:41:00.000Z",
      "expires_at": null,
      "expires_at_date": null,
      "issued_at": "2014-04-01T14:41:00.000Z",
      "issued_at_date": "2014-04-01",
      "state_updated_at": null,
      "image": {
        "id": "fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba",
        "url": "/system/test/images/fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "alignments": [
        {
          "name": "Alignment 5",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "evidence": [

      ],
      "accept_badge_url": "https://localhost/badges/1b06d9ad-f2d9-44e9-8bf2-86b7785ef473/accept"
    },
    {
      "user": {
        "id": "c778edc9-1f30-4dc9-9e19-c7d9143e51ae",
        "email": "c778edc9-1f30-4dc9-9e19-c7d9143e51ae@example.com",
        "first_name": "Alfred",
        "last_name": "Skiles",
        "current_position_name": "*****",
        "current_organization_name": "*****",
        "confirmed": true,
        "photo": null,
        "photo_url": null,
        "url": "https://localhost/user/alfred-skiles.928e44f9"
      },
      "printing_enabled": false,
      "issuer": {
        "type": "Organization",
        "id": "ef04c4d3-de56-489f-bfab-79292f82f2dc",
        "name": "Organization 10",
        "url": "https://api.youracclaim.com/v1/organizations/ef04c4d3-de56-489f-bfab-79292f82f2dc",
        "vanity_url": "https://localhost/org/organization-10",
        "verified": true
      },
      "badge_template": {
        "id": "ffc28f60-d525-43de-94f7-715c697f69c2",
        "description": "Dynamically deliver go forward e-tailers",
        "global_activity_url": "https://www.example.com/foo",
        "name": "Badge Template 5",
        "state": "active",
        "public": true,
        "badges_count": 2,
        "recipient_type": "User",
        "show_badge_lmi": false,
        "show_lmi_jobs": false,
        "show_skill_tag_links": true,
        "vanity_slug": "badge-template-5",
        "criteria_url_name": null,
        "criteria_url": null,
        "certification": true,
        "state_updated_at": null,
        "created_at": "2014-04-01T14:41:00.000Z",
        "updated_at": "2014-04-01T14:41:00.000Z",
        "template_type": "skill",
        "show_template_settings": false,
        "get_issue_count": 2,
        "image": {
          "id": "fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba",
          "url": "/system/test/images/fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba/fake-352x352.png"
        },
        "image_url": "https://cdn.example.com/path/to/image.png",
        "url": "https://localhost/org/organization-10/badge/badge-template-5",
        "owner": {
          "type": "Organization",
          "id": "ef04c4d3-de56-489f-bfab-79292f82f2dc",
          "name": "Organization 10",
          "url": "https://api.youracclaim.com/v1/organizations/ef04c4d3-de56-489f-bfab-79292f82f2dc",
          "vanity_url": "https://localhost/org/organization-10",
          "vanity_slug": "organization-10",
          "verified": true,
          "viewable": true
        },
        "alignments": [
          {
            "id": "2641cc39-478e-4032-8dee-e3dcfcc86e12",
            "name": "Alignment 5",
            "url": "http://www.example.com/alignment",
            "description": "Self-enabling cohesive task-force"
          }
        ],
        "recommendations": [
          {
            "id": "5392e710-b410-4958-b046-8598fb22212e",
            "title": "Go to this URL immediately!",
            "type": "url",
            "activity_url": "http://www.example.com/recommendation"
          }
        ],
        "required_badge_templates": [

        ],
        "badge_template_activities": [
          {
            "id": "b544b81b-64b1-4900-b464-7f042d89323d",
            "title": "Kickboxing Activity",
            "activity_type": "Schedule / Registration",
            "activity_url": "http://www.example.com/awesomepage",
            "required_badge_template_id": null
          }
        ],
        "skills": [
          "Skill 5"
        ]
      },
      "id": "d00bbb55-f7a3-46a8-9a08-d379ddd363e3",
      "issued_to": "Alfred Skiles",
      "issued_to_first_name": "Alfred",
      "issued_to_last_name": "Skiles",
      "issuer_earner_id": null,
      "locale": "en",
      "public": true,
      "recipient_email": "user7@example.com",
      "replacement_badge_id": null,
      "revocation_reason": null,
      "state": "pending",
      "suppress_badge_notification_email": false,
      "created_at": "2014-04-01T14:41:00.000Z",
      "expires_at": null,
      "expires_at_date": null,
      "issued_at": "2014-04-01T14:41:00.000Z",
      "issued_at_date": "2014-04-01",
      "state_updated_at": null,
      "image": {
        "id": "fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba",
        "url": "/system/test/images/fe6d88b4-96a7-4fed-95b2-0c8b48fa2cba/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "alignments": [
        {
          "name": "Alignment 5",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "evidence": [

      ],
      "accept_badge_url": "https://localhost/badges/d00bbb55-f7a3-46a8-9a08-d379ddd363e3/accept"
    }
  ],
  "metadata": {
  }
}

Error Response

If we sent a batch of badge information in which the second badge was missing an issued_at date, we'd get the following response:

422 Unprocessable Entity

{
  "data": {
    "message": "Validation failed: Issued at can't be blank",
    "errors": [
      {
        "attribute": "issued_at",
        "attribute_label": "Issued at",
        "messages": [ "can't be blank" ]
      }
    ],
    "error_index": 1
  }
}

Get Issued Badges

Request

GET /organizations/<organization_id>/badges
Query Param Description
filter=<filter> Gets badges issued by the specified organization that match the filter
sort=<sort> Sorts the results based on the sort parameter
page=<page_number> Gets the specified page of badges with the specified state issued by the specified organization

Filtering

The filter parameter has the following format: key::value. You can combine keys for stricter searches, e.g. state::pending|user_id::42.

Results can be filtered with the following keys:

Key Description
query Partial matches on badge template name, user full name, or user email address (partial email address matches beginning with '@' e.g. @example.com or @*.example.com)
state Returns badges in the specified state (pending, accepted, rejected, revoked); allows multiple states delimited by comma
user_id Returns badges for the user with the specified user ID
issued_at_min Returns badges with issue date on or after the specified date (YYYY-MM-DD)
issued_at_max Returns badges with issue date on or before the specified date (YYYY-MM-DD)
issued_at_date_min Returns badges with the time zone-agnostic issue date on or after the specified date (YYYY-MM-DD)
issued_at_date_max Returns badges with the time zone-agnostic issue date on or before the specified date (YYYY-MM-DD)
issuer_id Returns badges issued by an organization with the specified ID; allows multiple IDs delimited by comma
issuer_earner_id Returns badges with the specified issuer earner ID
public Returns badges that are public or non-public for specified true or false value
badge_templates[reporting_tags] Returns badges with specified reporting tags as a comma delimited list
badge_templates[skills] Returns badges matching any of the skills specified as a comma delimited list
created_at_min Returns badges created on or after the specified date (YYYY-MM-DD)
created_at_max Returns badges created on or before the specified date (YYYY-MM-DD)
state_updated_at_min Returns badges with state change on or after the specified date (YYYY-MM-DD)
state_updated_at_max Returns badges with state change on or before the specified date (YYYY-MM-DD)
updated_at_min Returns badges with change on or after the specified date (YYYY-MM-DD)
updated_at_max Returns badges with change on or before the specified date (YYYY-MM-DD)
badge_template_id Returns badges with the specified badge template ID; allows multiple IDs delimited by comma
badge_templates[owner_id] Returns issued badges owned by an organization with the specified ID; allows multiple IDs delimited by comma

Sorting

The sort parameter has the following format: key1|key2. You can optionally include a - to indicate descending order. e.g. -issued_at would return results in order with the most recently issued badges first.

Results can be sorted with the following keys:

Key Description
created_at Date the badge was created
issued_at Date the badge was issued
state_updated_at Date the badge's state was updated (pending, accepted, rejected, revoked)
badge_templates[name] Name of the badge template
users[first_name] First name of the user that the badge was issued to
users[last_name] Last name of the user that the badge was issued to

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": [
    {
      "user": {
        "id": "46cd20e3-f1e8-4c0e-9a96-60152ced3000",
        "email": "46cd20e3-f1e8-4c0e-9a96-60152ced3000@example.com",
        "first_name": "Alfred",
        "last_name": "Skiles",
        "current_position_name": "*****",
        "current_organization_name": "*****",
        "confirmed": true,
        "photo": null,
        "photo_url": null,
        "url": "https://localhost/user/alfred-skiles.412ca647"
      },
      "printing_enabled": false,
      "issuer": {
        "type": "Organization",
        "id": "20be75f6-4b33-4609-a1dd-9c340afa1a8f",
        "name": "Organization 1",
        "url": "https://api.youracclaim.com/v1/organizations/20be75f6-4b33-4609-a1dd-9c340afa1a8f",
        "vanity_url": "https://localhost/org/organization-1",
        "verified": true
      },
      "badge_template": {
        "id": "09d1ac8b-d097-4ae4-844a-a2ae01d1bdbe",
        "description": "Dynamically deliver go forward e-tailers",
        "global_activity_url": "https://www.example.com/foo",
        "name": "Badge Template 1",
        "state": "active",
        "public": true,
        "badges_count": 0,
        "recipient_type": "User",
        "show_badge_lmi": false,
        "show_lmi_jobs": false,
        "show_skill_tag_links": true,
        "vanity_slug": "badge-template-1",
        "criteria_url_name": null,
        "criteria_url": null,
        "certification": true,
        "state_updated_at": null,
        "created_at": "2014-04-01T14:41:00.000Z",
        "updated_at": "2014-04-01T14:41:00.000Z",
        "template_type": "skill",
        "show_template_settings": false,
        "get_issue_count": 0,
        "image": {
          "id": "5ef66a91-3799-4ccd-a7f3-71f35714041d",
          "url": "/system/test/images/5ef66a91-3799-4ccd-a7f3-71f35714041d/fake-352x352.png"
        },
        "image_url": "https://cdn.example.com/path/to/image.png",
        "url": "https://localhost/org/organization-1/badge/badge-template-1",
        "owner": {
          "type": "Organization",
          "id": "20be75f6-4b33-4609-a1dd-9c340afa1a8f",
          "name": "Organization 1",
          "url": "https://api.youracclaim.com/v1/organizations/20be75f6-4b33-4609-a1dd-9c340afa1a8f",
          "vanity_url": "https://localhost/org/organization-1",
          "vanity_slug": "organization-1",
          "verified": true,
          "viewable": true
        },
        "alignments": [
          {
            "id": "4b901d3b-a448-42a0-938e-23c5b306c487",
            "name": "Alignment 1",
            "url": "http://www.example.com/alignment",
            "description": "Self-enabling cohesive task-force"
          }
        ],
        "recommendations": [
          {
            "id": "6836a63a-5078-49f1-95c8-10f9f2e83d3b",
            "title": "Go to this URL immediately!",
            "type": "url",
            "activity_url": "http://www.example.com/recommendation"
          }
        ],
        "required_badge_templates": [

        ],
        "badge_template_activities": [
          {
            "id": "bd22eda5-e9a2-443c-8875-227fd44518b5",
            "title": "Kickboxing Activity",
            "activity_type": "Schedule / Registration",
            "activity_url": "http://www.example.com/awesomepage",
            "required_badge_template_id": null
          }
        ],
        "skills": [
          "Skill 1"
        ]
      },
      "id": "749daf6e-4dbc-4b47-b401-b7e0477e0284",
      "issued_to": "Alfred Skiles",
      "issued_to_first_name": "Alfred",
      "issued_to_last_name": "Skiles",
      "issuer_earner_id": null,
      "locale": "en",
      "public": true,
      "recipient_email": "user10001@example.com",
      "replacement_badge_id": null,
      "revocation_reason": null,
      "state": "accepted",
      "suppress_badge_notification_email": false,
      "created_at": "2014-04-01T14:41:00.000Z",
      "expires_at": "2016-04-01T14:41:00.000Z",
      "expires_at_date": "2016-04-01",
      "issued_at": "2014-04-01T14:41:00.000Z",
      "issued_at_date": "2014-04-01",
      "state_updated_at": "2017-09-18T12:14:51.331Z",
      "image": {
        "id": "5ef66a91-3799-4ccd-a7f3-71f35714041d",
        "url": "/system/test/images/5ef66a91-3799-4ccd-a7f3-71f35714041d/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "alignments": [
        {
          "name": "Alignment 1",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "evidence": [
        {
          "id": "83aee9be-57b6-4518-b8e3-1d5b5961a0b1",
          "type": "UrlEvidence",
          "name": "Acclaim",
          "description": "Description in URL evidence is optional",
          "value": "http://www.example.com/path-to-earner-specific-evidence"
        }
      ],
      "badge_url": "https://localhost/badges/749daf6e-4dbc-4b47-b401-b7e0477e0284"
    }
  ],
  "metadata": {
    "count": 1,
    "current_page": 1,
    "total_count": 1,
    "total_pages": 1,
    "previous_page_url": null,
    "next_page_url": null
  }
}

Get Badges in Bulk

You can get large amounts of badge data more efficiently by using an endpoint similar to Get Issued Badges

Query Param Description
filter=<filter> Gets badges issued by the specified organization that match the filter
badge_format=<format_name> Determines the response payload content can be default or minimal

Request

GET /organizations/<organization_id>/high_volume_issued_badge_search

Filtering

This endpoint supports the same filtering options available for Badge Search Filters

Paging

The only paging mechanism available is a forward cursor. The url returned in the next_page_url will be not empty when there is more data to obtain. To cursor through the results, repeatedly request the url returned in next_page_url until its null in value.

Badge Response Formats

Default

The default response format contains most of the same badge and badge template information as the Get Issued Badges endpoint. It is useful when a moderate amount of data is required at the cost of performance.

{
  "data": [
    {
      "id": "9f53aa64-ce37-4dbe-b6bb-b6d0f02c774d1",
      "issued_to": "Alfred Skiles",
      "issued_to_first_name": "Alfred",
      "issued_to_last_name": "Skiles",
      "issuer_earner_id": null,
      "locale": "en",
      "public": true,
      "recipient_email": "user1@example.com",
      "replacement_badge_id": null,
      "revocation_reason": null,
      "state": "accepted",
      "suppress_badge_notification_email": false,
      "created_at": "2017-06-26T17:44:01.842Z",
      "expires_at": null,
      "expires_at_date": null,
      "issued_at": "2013-04-14T05:00:00.000Z",
      "issued_at_date": "2013-04-14",
      "state_updated_at": null,
      "badge_url": "https://localhost/badges/9f53aa64-ce37-4dbe-b6bb-b6d0f02c774d",
      "issuer": {
        "type": "Organization",
        "id": "296087f5-6820-44c6-93aa-cea556aca312"
      },
      "badge_template": {
        "id": "f4cdea64-205e-454b-a8c9-6fbed87c28a8",
        "description": "Suspendisse sagittis posuere mi nec pharetra. Proin mattis nisl nec commodo tincidunt. Morbi ac scelerisque risus. Mauris vulputate ornare dolor.",
        "global_activity_url": "https://example.com",
        "name": "Softball",
        "state": "active",
        "public": true,
        "vanity_slug": "softball",
        "state_updated_at": null,
        "created_at": "2017-06-26T17:43:38.607Z",
        "updated_at": "2017-06-26T17:43:39.488Z",
        "image": {
          "id": "12620dc3-768d-4a9f-9cbe-f447977c300e",
          "url": "https://cdn.example.com/9b77b9d8-ff8f-4dbd-a177-8b1fc2cc0f88/fake-352x352.png"
       },
      "image_url": "https://cdn.example.com/9b77b9d8-ff8f-4dbd-a177-8b1fc2cc0f98/fake-352x352.png",
      "url": "https://localhost/org/organization-1/badge/badge-template-1",
      "owner": {
        "type": "Organization",
        "id": "296087f5-6820-44c6-93aa-cea556aca312"
      }
    }
  ],
  "metadata": {
    "next_page_url": null
  }

Minimal

The minimal response format has just enough information to identify the badges returned and view some minimal information about them. This format is best used when large amounts of data are needed in a short time.

{
  "data": [
    "id": "f605541c-7091-44a9-a0dd-112981ae3391",
    "issued_to": "Alfred Skiles",
    "issued_to_first_name": "Alfred",
    "issued_to_last_name": "Skiles",
    "issuer_earner_id": null,
    "public": true,
    "recipient_email": "user1@example.com",
    "state": "accepted",
    "created_at": "2017-06-26T17:44:01.842Z",
    "expires_at": null,
    "issued_at": "2013-04-14T05:00:00.000Z",
    "state_updated_at": null,
    "badge_template": {
      "id": "f4cdea64-205e-454b-a8c9-6fbed87c28a8",
      "name": "Softball"
    }
  }
  ],
  "metadata": {
    "next_page_url": null
  }
}

Replace a Badge

Replacing a badge will create a new badge to take the place of an existing one. Badge template ID, earner first and last name, issuer earner ID, issue date, expiration date, and evidence can all be changed. Fields that are not provided will not assume the values from the replaced badge. For example, if expiration date is not provided the new badge will not expire. If a notification message is included, the badge's recipient will receive an email including that message.

The recipientemail may be changed on a replacement, however this feature is only available on badges with a state of pending. Providing a change of recipientemail on badges in other states will result in an error.

If attempts are made to access the old badge, the service will return a redirect to the new badge's location.

Request

POST /organizations/<organization_id>/badges/<badge_id>/replace

Request Body

{
  "badge_template_id": "4008b9b1-1251-40a3-ba90-1bbc9720fc37",
  "issued_at": "2014-04-01 09:41:00 -0500",
  "issued_to": "Firstname Lastname",
  "issued_to_first_name": "Firstname",
  "issued_to_last_name": "Lastname",
  "issuer_earner_id": "earner-1",
  "expires_at": null,
  "evidence": [
    {
      "type": "UrlEvidence",
      "value": "http://www.example.com/evidence",
      "description": "Description in URL evidence is optional",
      "name": "Evidence"
    }
  ],
  "notification_message": "Lorem ipsum dolor"
}

Response

201 Created Location: <badge_url>

{
  "data": {
    "user": {
      "id": "f5284c88-6666-4c39-b9d0-8f2bbead379e",
      "email": "f5284c88-6666-4c39-b9d0-8f2bbead379e@example.com",
      "first_name": "Alfred",
      "last_name": "Skiles",
      "current_position_name": "*****",
      "current_organization_name": "*****",
      "confirmed": true,
      "photo": null,
      "photo_url": null,
      "url": "https://localhost/user/alfred-skiles"
    },
    "printing_enabled": false,
    "issuer": {
      "type": "Organization",
      "id": "70a02fd3-ce3f-41b2-833f-84bb1742a41a",
      "name": "Organization 6",
      "url": "https://api.youracclaim.com/v1/organizations/70a02fd3-ce3f-41b2-833f-84bb1742a41a",
      "vanity_url": "https://localhost/org/organization-6",
      "verified": true
    },
    "badge_template": {
      "id": "664ec77c-809f-4069-ad4f-161ddb211f02",
      "description": "Dynamically deliver go forward e-tailers",
      "global_activity_url": "https://www.example.com/foo",
      "name": "Badge Template 3",
      "state": "active",
      "public": true,
      "badges_count": 0,
      "recipient_type": "User",
      "show_badge_lmi": false,
      "show_lmi_jobs": false,
      "show_skill_tag_links": true,
      "vanity_slug": "badge-template-3",
      "criteria_url_name": null,
      "criteria_url": null,
      "certification": true,
      "state_updated_at": null,
      "created_at": "2014-04-01T14:41:00.000Z",
      "updated_at": "2014-04-01T14:41:00.000Z",
      "template_type": "skill",
      "show_template_settings": false,
      "get_issue_count": 0,
      "image": {
        "id": "9880ceec-0ec3-499d-b8f1-4dda1d9fa786",
        "url": "/system/test/images/9880ceec-0ec3-499d-b8f1-4dda1d9fa786/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "url": "https://localhost/org/organization-6/badge/badge-template-3",
      "owner": {
        "type": "Organization",
        "id": "70a02fd3-ce3f-41b2-833f-84bb1742a41a",
        "name": "Organization 6",
        "url": "https://api.youracclaim.com/v1/organizations/70a02fd3-ce3f-41b2-833f-84bb1742a41a",
        "vanity_url": "https://localhost/org/organization-6",
        "vanity_slug": "organization-6",
        "verified": true,
        "viewable": true
      },
      "alignments": [
        {
          "id": "744dfd4e-17fd-4bca-b1a1-8855604f3aef",
          "name": "Alignment 3",
          "url": "http://www.example.com/alignment",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "recommendations": [
        {
          "id": "2478740d-8aa1-41ca-b94f-3429a8cab218",
          "title": "Go to this URL immediately!",
          "type": "url",
          "activity_url": "http://www.example.com/recommendation"
        }
      ],
      "required_badge_templates": [

      ],
      "badge_template_activities": [
        {
          "id": "98cd5ceb-48d7-4ad0-84aa-8e6a56797777",
          "title": "Kickboxing Activity",
          "activity_type": "Schedule / Registration",
          "activity_url": "http://www.example.com/awesomepage",
          "required_badge_template_id": null
        }
      ],
      "skills": [
        "Skill 3"
      ]
    },
    "id": "8c31235d-fb44-4a9b-9242-502a745e9b71",
    "issued_to": "Firstname Lastname",
    "issued_to_first_name": "Firstname",
    "issued_to_last_name": "Lastname",
    "issuer_earner_id": "earner-1",
    "locale": "en",
    "public": true,
    "recipient_email": "user2@example.com",
    "replacement_badge_id": null,
    "revocation_reason": null,
    "state": "accepted",
    "suppress_badge_notification_email": false,
    "created_at": "2014-04-01T14:41:00.000Z",
    "expires_at": null,
    "expires_at_date": null,
    "issued_at": "2014-04-01T14:41:00.000Z",
    "issued_at_date": "2014-04-01",
    "state_updated_at": "2017-02-08T21:54:33.509Z",
    "image": {
      "id": "9880ceec-0ec3-499d-b8f1-4dda1d9fa786",
      "url": "/system/test/images/9880ceec-0ec3-499d-b8f1-4dda1d9fa786/fake-352x352.png"
    },
    "image_url": "https://cdn.example.com/path/to/image.png",
    "alignments": [
      {
        "name": "Alignment 3",
        "description": "Self-enabling cohesive task-force"
      }
    ],
    "evidence": [
      {
        "id": "a2b2271e-2dab-4ff3-bc04-ce1067923b98",
        "type": "UrlEvidence",
        "name": "Evidence",
        "description": "Description in URL evidence is optional",
        "value": "http://www.example.com/evidence"
      }
    ],
    "accept_badge_url": "https://localhost/badges/8c31235d-fb44-4a9b-9242-502a745e9b71/accept",
    "badge_url": "https://localhost/badges/8c31235d-fb44-4a9b-9242-502a745e9b71"
  },
  "metadata": {
  }
}

Revoke a Badge

Revoking a badge will cause requests to the badge's OBI hosted assertion (/api/v1/obi/badgeassertions/<badgeid>) to return HTTP 410 Gone.

Request

PUT /organizations/<organization_id>/badges/<badge_id>/revoke

Request Body

{
  "reason": "Check bounced",
  "suppress_revoke_notification_email": false
}

suppress_revoke_notification_email is optional. Set it to true to suppress the email notification that is ordinarily sent to the earner when a badge is revoked.

Response

200 OK

{
  "data": {
    "user": {
      "id": "184008bd-78fd-4463-9e4a-c3334b872f68",
      "email": "184008bd-78fd-4463-9e4a-c3334b872f68@example.com",
      "first_name": "Alfred",
      "last_name": "Skiles",
      "current_position_name": "*****",
      "current_organization_name": "*****",
      "confirmed": true,
      "photo": null,
      "photo_url": null,
      "url": "https://localhost/user/alfred-skiles"
    },
    "printing_enabled": false,
    "issuer": {
      "type": "Organization",
      "id": "ee9ff4d9-9120-48e5-90a5-138ead443d41",
      "name": "Organization 3",
      "url": "https://api.youracclaim.com/v1/organizations/ee9ff4d9-9120-48e5-90a5-138ead443d41",
      "vanity_url": "https://localhost/org/organization-3",
      "verified": true
    },
    "badge_template": {
      "id": "43aaea02-e847-44b8-a4d6-a7e69bfebf1f",
      "description": "Dynamically deliver go forward e-tailers",
      "global_activity_url": "https://www.example.com/foo",
      "name": "Badge Template 2",
      "state": "active",
      "public": true,
      "badges_count": 0,
      "recipient_type": "User",
      "show_badge_lmi": false,
      "show_lmi_jobs": false,
      "show_skill_tag_links": true,
      "vanity_slug": "badge-template-2",
      "criteria_url_name": null,
      "criteria_url": null,
      "certification": true,
      "state_updated_at": null,
      "created_at": "2014-04-01T14:41:00.000Z",
      "updated_at": "2014-04-01T14:41:00.000Z",
      "template_type": "skill",
      "show_template_settings": false,
      "get_issue_count": 0,
      "image": {
        "id": "c4f9be0b-bcb6-4d5b-815e-6b57ce1187ec",
        "url": "/system/test/images/c4f9be0b-bcb6-4d5b-815e-6b57ce1187ec/fake-352x352.png"
      },
      "image_url": "https://cdn.example.com/path/to/image.png",
      "url": "https://localhost/org/organization-3/badge/badge-template-2",
      "owner": {
        "type": "Organization",
        "id": "ee9ff4d9-9120-48e5-90a5-138ead443d41",
        "name": "Organization 3",
        "url": "https://api.youracclaim.com/v1/organizations/ee9ff4d9-9120-48e5-90a5-138ead443d41",
        "vanity_url": "https://localhost/org/organization-3",
        "vanity_slug": "organization-3",
        "verified": true,
        "viewable": true
      },
      "alignments": [
        {
          "id": "bea03e89-0ffe-4f2a-80b7-4884881fce28",
          "name": "Alignment 2",
          "url": "http://www.example.com/alignment",
          "description": "Self-enabling cohesive task-force"
        }
      ],
      "recommendations": [
        {
          "id": "2af89b7e-29b9-4c8b-ae42-32d19d56a1b3",
          "title": "Go to this URL immediately!",
          "type": "url",
          "activity_url": "http://www.example.com/recommendation"
        }
      ],
      "required_badge_templates": [

      ],
      "badge_template_activities": [
        {
          "id": "8f843d36-e076-4d4b-8a38-cc462e1dd098",
          "title": "Kickboxing Activity",
          "activity_type": "Schedule / Registration",
          "activity_url": "http://www.example.com/awesomepage",
          "required_badge_template_id": null
        }
      ],
      "skills": [
        "Skill 2"
      ]
    },
    "id": "7c7f7e1f-62a1-44e0-bf66-83891376807b",
    "issued_to": "Alfred Skiles",
    "issued_to_first_name": "Alfred",
    "issued_to_last_name": "Skiles",
    "issuer_earner_id": null,
    "locale": "en",
    "public": true,
    "recipient_email": "user10001@example.com",
    "replacement_badge_id": null,
    "revocation_reason": "Check bounced",
    "state": "revoked",
    "suppress_badge_notification_email": false,
    "created_at": "2014-04-01T14:41:00.000Z",
    "expires_at": "2016-04-01T14:41:00.000Z",
    "expires_at_date": "2016-04-01",
    "issued_at": "2014-04-01T14:41:00.000Z",
    "issued_at_date": "2014-04-01",
    "state_updated_at": "2014-04-01T14:41:00.000Z",
    "image": {
      "id": "c4f9be0b-bcb6-4d5b-815e-6b57ce1187ec",
      "url": "/system/test/images/c4f9be0b-bcb6-4d5b-815e-6b57ce1187ec/fake-352x352.png"
    },
    "image_url": "https://cdn.example.com/path/to/image.png",
    "alignments": [
      {
        "name": "Alignment 2",
        "description": "Self-enabling cohesive task-force"
      }
    ],
    "evidence": [
      {
        "id": "a3b1477d-f79f-4176-93db-3e73c2f2cf5c",
        "type": "UrlEvidence",
        "name": "Acclaim",
        "description": "Description in URL evidence is optional",
        "value": "http://www.example.com/path-to-earner-specific-evidence"
      }
    ]
  },
  "metadata": {
  }
}