+ "description": "The [Accredible](https://www.accredible.com/) Credential API allows you to create and interact with badges and certificates called [Accredible Credentials](https://www.credential.net/10000005).\n\nThere are 3 main objects in Accredible: Credentials, Groups and Designs.\n\n### Getting Started with the API - Video Walkthrough\n\n[](https://www.loom.com/share/1093916cb4be421eb1ff86f085dae337?sid=0bb24e68-c7b4-41a6-aab8-f5c14841a29c)\n\n# Objects Overview\n## Credentials\n[Credentials](#tag/Credentials) are the core object in the API. They collect all of the data related to a course, training activity or achievement and the recipient/participant information.\n\nYou should create a credential for each achievement completion that a recipient has. For example if John Doe finishes the Programming 101 course we should create one credential to represent that. If John Doe achieves something else then he would need a new credential.\n\n## Groups\n\n[Groups](#tag/Groups) represent an achievement such as a course or qualification. They contain information about the achievement and have multiple Credentials attached to them.\n\nFor example you should create a group for the Introduction to Programming course. You'd provide the Course Name, Course Description and Course URL. In the future you can pass the name or ID of this group when creating a credential so that the credential is passed all the information relating to the achievement.\n\n## Designs\n\n[Designs](#tag/Designs) provide a visual specification for how a Credential should be rendered. Designs can be used across multiple Groups.\n\nFor example if we have three courses: Intro to Basic Programming, Intro to Advanced Programming and Intro to DevOps each of these may have the same design for their Credentials. When creating or updating their corresponding Groups you would attach the desired design accordingly.\n\n## Departments\n\n[Departments](#tag/Departments), if enabled for your account allow you to manage multiple, independent organization groups. Each Department is entirely separate with its own Designs, Groups, Branding, etc. You cannot share data between Departments except Billing and Administrators.\n\n## Attributes\n\n[Attributes](#tag/Attributes), are used to merge information with your badge or certificate designs and email templates. Attributes act as placeholders for information and can be added to certificate designs and email templates.\n\n# API Keys\n\nAPI keys are used as Authorization tokens in the header in all authenticated API endpoints. These Keys are managed in the [Accredible Dashboard](https://dashboard.accredible.com/). There are two types of API Keys, those that are account wide and work on all assets and those that are related to a specific department. API keys scoped to a specific department can only access the resources (Credentials, Groups, Designs etc.) belonging to that department.\n\n# Single sign-on options\n\n[Single sign-on](#tag/SSO) in addition to the student authentication provided by Accredible, you can also use single sign-on to authenticate your student into Accredible and they can directly sign-in.\n\nSSO is also available via our Integrations and via SAML 2.0.\n\n# Rate Limiting\n\nWe allow up to 2000 requests every 5 minutes from a single IP address, but some higher security endpoints have stricter rate limiting. Requests are counted in 30 second periods.\n\nIf you attempt to make requests more quickly than permitted by these rules, you may receive a `429 Too Many Requests` response from an endpoint.\n\n# Errors\n\nAccredible uses conventional HTTP response codes to indicate the success or failure of an API request. Most error response formats are consistent across API versions, with some differences in bulk operations.\n\n## HTTP Status Codes\n\n| Status Code | Description |\n| ----------- | ----------- |\n| **2xx** | Success |\n| 200 | OK - The request was successful |\n| 207 | Multi-Status - Partial success in batch operations (v2 only) |\n| **4xx** | Client Error |\n| 400 | Bad Request - Invalid request parameters |\n| 401 | Unauthorized - Invalid or missing API key |\n| 403 | Forbidden - Insufficient permissions |\n| 404 | Not Found - Resource not found |\n| 422 | Unprocessable Entity - Validation errors |\n| 429 | Too Many Requests - Rate limit exceeded |\n| **5xx** | Server Error |\n| 500 | Internal Server Error |\n\n## Common Error Formats\n\nMost API endpoints use these standard error formats:\n\n**Search Query Errors (400)**\n```json\n{\n \"code\": 400,\n \"message\": \"Sort order increasing is not supported\",\n \"status\": \"invalid_search_query\",\n \"errors\": {}\n}\n```\n\n**Unauthorized (401):**\n```\nHTTP Token: Access denied.\n```\n\n```json\n{\n \"success\": false,\n \"data\": \"Not enough or too many segments\"\n}\n```\n\n```json\n{\n \"success\": false,\n \"data\": \"Sorry, You are not authorized, visit accredible.com for this\"\n}\n```\n\n**Forbidden (403):**\n```json\n{\n \"errors\": \"Private Certificate, use key\"\n}\n```\n\n**Not Found (404):**\n```json\n{\n \"errors\": \"Doesn't exist\"\n}\n```\n\n```json\n{\n \"error\": \"Not found\"\n}\n```\n\n```json\n{\n \"success\": false,\n \"data\": \"Group does not exist\"\n}\n```\n\n**Unprocessable Entity (422):**\n```json\n{\n \"errors\": \"Invalid Group\"\n}\n```\n\n```json\n{\n \"errors\": \"Can not create credential without recipient data\"\n}\n```\n\n```json\n{\n \"errors\": {\n \"course_name\": [\n \"can't be blank\"\n ],\n \"course_description\": [\n \"can't be blank\"\n ]\n }\n}\n```\n\n**Internal Server Error (500):**\n```json\n{\n \"errors\": \"Internal server error\"\n}\n```\n\n## Bulk Operations Error Handling\n\n### V2 Bulk Create (Mixed Results Supported)\n\n**All Successful (200):**\n```json\n{\n \"results\": [\n {\n \"credential\": { /* credential object */ }\n },\n {\n \"credential\": { /* credential object */ }\n }\n ]\n}\n```\n\n**Mixed Success/Failure (207 Multi-Status):**\n```json\n{\n \"results\": [\n {\n \"credential\": { /* successful credential */ }\n },\n {\n \"error\": {\n \"code\": \"credential_invalid\",\n \"message\": \"The credential is not valid\",\n \"details\": [\n {\n \"property\": \"recipient_name\",\n \"reason\": \"blank\"\n }\n ]\n }\n },\n {\n \"credential\": { /* successful but unpublished */ },\n \"error\": {\n \"code\": \"insufficient_credits\",\n \"message\": \"The credential was created but not published\"\n }\n }\n ]\n}\n```\n\n**All Failed (422):**\n```json\n{\n \"results\": [\n {\n \"error\": {\n \"code\": \"credential_invalid\",\n \"message\": \"The credential is not valid\",\n \"details\": [\n {\n \"property\": \"course_name\",\n \"reason\": \"blank\"\n }\n ]\n }\n }\n ]\n}\n```\n"
0 commit comments