Workforce

Note that information on workforce related webhooks can be found here.

Get Employees

Request

GET /organizations/<organization_id>/employees
Query Param Description
filter=<filter> Gets employees that match the specified filter
sort=<sort> Sorts the results based on the sort parameter
page=<page_number> Gets the specified page of employees

Filtering

The filter parameter has the following format: filter[key]=value. You can combine keys for stricter searches, e.g. filter[state]=accepted&filter[name_or_email]=johndoe@gmail.com.

Results can be filtered with the following keys:

Key Description
name_or_email Partial matches on the employee name or email address used to invite or create the employee
employee_state One of created, accepted, rejected, or pending
badge_level One of Foundational, Intermediate, Advanced

Deprecated Filtering:

The following syntax is deprecated in favor of the above, however it is still supported. The filter parameter may have the following format: key::value. You can combine keys for stricter searches, e.g. state::accepted|name_or_email::johndoe@gmail.com.

Sorting

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

Results can be sorted with the following keys:

Key Description
email Email address used to create the employee
created_at Timestamp of when the employee was created
first_name First name of the employee
last_name Last name of the employee

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": "377f7425-bd03-418b-92af-ea20219fd6e6",
      "email": "email5@example.com",
      "created_at": "2014-04-01T14:41:00.000Z",
      "employee_state": "pending",
      "employee_state_updated_at": "2014-04-01T14:41:00.000Z",
      "last_invitation_sent_at": null,
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "photo_url": null,
      "team": "Development",
      "external_id": null,
      "position_title": "Front End",
      "manager_first_name": null,
      "manager_last_name": null,
      "manager_external_id": null,
      "location": null,
      "country": null,
      "zip_code": null,
      "state_or_province": null,
      "department": "Engineering",
      "organization_level_1": "Farming",
      "organization_level_2": "Aquatic",
      "organization_level_3": "Kelp",
      "job_family": "f100"
    }
  ],
  "metadata": {
    "count": 1,
    "current_page": 1,
    "total_count": 1,
    "total_pages": 1,
    "per": 50,
    "previous_page_url": null,
    "next_page_url": null
  }
}

Get a Single Employee

Request

GET /organizations/<organization_id>/employees/<employee_id>

URL Parameters

Param Description
organization_id Id of the organization retrieving employee data for
employee_id Value can either be email of the employee, or external_id
external_id Id value that is used by the employer to internally track employees

Response

200 OK

{
  "data": {
    "id": "89e5edda-1b2c-4e1f-b5b7-38eb4a7884b5",
    "email": "email4@example.com",
    "created_at": "2014-04-01T14:41:00.000Z",
    "employee_state": "pending",
    "employee_state_updated_at": "2014-04-01T14:41:00.000Z",
    "last_invitation_sent_at": null,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "photo_url": null,
    "team": "Development",
    "external_id": null,
    "position_title": "Front End",
    "manager_first_name": null,
    "manager_last_name": null,
    "manager_external_id": null,
    "location": null,
    "country": null,
    "zip_code": null,
    "state_or_province": null,
    "department": "Engineering",
    "organization_level_1": "Farming",
    "organization_level_2": "Aquatic",
    "organization_level_3": "Kelp",
    "job_family": "f100"
  },
  "metadata": {
  }
}

Create an Employee

Request

POST /organizations/<organization_id>/employees

The minimum required fields to create employee records on the Credly Platform will vary depending on the customer tier your Workforce Organization belongs to: Credly Workforce and Unified Platform.

The minimum required fields for a "Credly Workforce" tier is documented here, please see further down below for documentation for the "Unified Platform" tier. If you are unsure what customer tier your organization belongs to please contact Credly Support at https://support.credly.com/hc/en-us/requests/new

Parameters - Credly Workforce

Required fields are in bold.

Name Description
email Email address of the employee.
first_name First name of the employee.
last_name Last name of the employee
team The team of the employee.
external_id Id value that is used by the employer to internally track employees
position_title Employee title
manager_first_name Employee manager's first name
manager_last_name Employee manager's last name
manager_external_id Employee manager's internal id used from employer if used
country Employee country
zip_code Employee zip code
state_or_province Employee state or province (US/CA)
department Employee department
job_family Additional metadata used for occupation matching
organization_level_1 Additional metadata used for occupation matching
organization_level_2 Additional metadata used for occupation matching
organization_level_3 Additional metadata used for occupation matching

Parameters - Unified Platform

Required fields are in bold.

Name Description
email Email address of the employee.
first_name First name of the employee.
last_name Last name of the employee
team The team of the employee.
external_id Id value that is used by the employer to internally track employees
position_title Employee title
manager_first_name Employee manager's first name
manager_last_name Employee manager's last name
manager_external_id Employee manager's internal id used from employer if used
country Employee country
zip_code Employee zip code
state_or_province Employee state or province (US/CA)
department Employee department
job_family Additional metadata used for occupation matching
organization_level_1 Additional metadata used for occupation matching
organization_level_2 Additional metadata used for occupation matching
organization_level_3 Additional metadata used for occupation matching

Request Body

  {
  "email": "email1@example.com",
  "first_name": "Alfred",
  "last_name": "Skiles",
  "team": "Development",
  "position_title": "Front End",
  "external_id": "employee-external-id-123",
  "manager_first_name": "Jane",
  "manager_last_name": "Doe",
  "manager_external_id": "manager-external-id-123",
  "country": "United States of America",
  "zip_code": "55347",
  "state_or_province": "Minnesota",
  "department": "Engineering",
  "organization_level_1": "Specialist",
  "organization_level_2": "Director",
  "organization_level_3": "Vice President",
  "job_family": "Human Resources"
}

Response

201 Created

{
  "data": {
    "id": "8ab46f92-28bb-4c77-a423-1b698923cc81",
    "email": "email1@example.com",
    "created_at": "2014-04-01T14:41:00.000Z",
    "employee_state": "created",
    "employee_state_updated_at": "2014-04-01T14:41:00.000Z",
    "last_invitation_sent_at": null,
    "first_name": "Alfred",
    "last_name": "Skiles",
    "full_name": "Alfred Skiles",
    "photo_url": null,
    "team": "Development",
    "external_id": "employee-external-id-123",
    "position_title": "Front End",
    "manager_first_name": "Jane",
    "manager_last_name": "Doe",
    "manager_external_id": "manager-external-id-123",
    "location": "Minnesota, United States of America",
    "country": "United States of America",
    "zip_code": "55347",
    "state_or_province": "Minnesota",
    "department": "Engineering",
    "organization_level_1": "Specialist",
    "organization_level_2": "Director",
    "organization_level_3": "Vice President",
    "job_family": "Human Resources"
  },
  "metadata": {
  }
}

Update an Employee

Request

PUT /organizations/<organization_id>/employees/<employee_id>

URL Parameters

Param Description
organization_id Id of the organization to update employee data for
employee_id Value can either be email of the employee, or external_id
external_id Id value that is used by the employer to internally track employees

Parameters

Name Description
first_name First name of the employee.
last_name Last name of the employee
team The team of the employee.
external_id Id value that is used by the employer to internally track employees
position_title Employee title
manager_first_name Employee manager's first name
manager_last_name Employee manager's last name
manager_external_id Employee manager's internal id used from employer if used
country Employee country
zip_code Employee zip code
state_or_province Employee state or province (US/CA)
department Employee department
organization_level_1 Employee organization level 1
organization_level_2 Employee organization level 2
organization_level_3 Employee organization level 3
job_family Employee job family

Request Body

{
  "first_name": "Alfred",
  "last_name": "Skiles",
  "team": "Development",
  "position_title": "Front End",
  "external_id": "employee-external-id-123",
  "manager_first_name": "Jane",
  "manager_last_name": "Doe",
  "manager_external_id": "manager-external-id-123",
  "country": "United States of America",
  "zip_code": "55347",
  "state_or_province": "Minnesota",
  "department": "Engineering",
  "organization_level_1": "Specialist",
  "organization_level_2": "Director",
  "organization_level_3": "Vice President",
  "job_family": "Human Resources"
}

Response

200 OK

{
  "data": {
    "id": "82121bbd-baaf-4018-ba6a-e6847ae30275",
    "email": "email2@example.com",
    "created_at": "2014-04-01T14:41:00.000Z",
    "employee_state": "pending",
    "employee_state_updated_at": "2014-04-01T14:41:00.000Z",
    "last_invitation_sent_at": null,
    "first_name": "Alfred",
    "last_name": "Skiles",
    "full_name": "Alfred Skiles",
    "photo_url": null,
    "team": "Development",
    "external_id": "employee-external-id-123",
    "position_title": "Front End",
    "manager_first_name": "Jane",
    "manager_last_name": "Doe",
    "manager_external_id": "manager-external-id-123",
    "location": "Minnesota, United States of America",
    "country": "United States of America",
    "zip_code": "55347",
    "state_or_province": "Minnesota",
    "department": "Engineering",
    "organization_level_1": "Specialist",
    "organization_level_2": "Director",
    "organization_level_3": "Vice President",
    "job_family": "Human Resources"
  },
  "metadata": {
  }
}

Invite an Employee

Request

POST /organizations/<organization_id>/employees/send_invitations

URL Parameters

Param Description
organization_id Id of the organization to invite employees for

Parameters

Name Description
employee_list Optional list of identifiers, the type of which defined by the value of list_type
list_type Required if employee_list is present. Must be one of email or external_id
statuses A list of values to filter the employees to invite by their employee_state. Can be created, pending, rejected, or left empty/omitted to target all states

Request Body

{
  "employee_list": ["external-id-1", "external-id-2"],
  "list_type": "external_id",
  "statuses": ["pending"]
}

Response

200 OK

{
  "data": {
    "resend_start": "2023-02-16T16:41:38.366Z"
  }
}

Delete an Employee

Request

DELETE /organizations/<organization_id>/employees/<employee_id>

Response

204 No Content

Employee Data API

The Employee Data API endpoint will allow employers to retrieve badge information related employees who have accepted a connection with them. The badges will include all employer issued badges as well as other public accepted badges that the employee has earned.

Request

GET /organizations/<organization_id>/employees/<employee_id>/data

URL Parameters

Param Description
organization_id Id of the organization retrieving employee data for
employee_id Value can either be email of the employee, or external_id
external_id Id value that is used by the employer to internally track employees

Response

200 OK

{
  "data": {
    "id": "be77d7d8-de09-4d73-8eeb-eb338541a93f",
    "email": "email312@example.com",
    "created_at": "2014-04-01T14:41:00.000Z",
    "employee_state": "accepted",
    "employee_state_updated_at": "2014-04-01T14:41:00.000Z",
    "last_invitation_sent_at": null,
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "photo_url": null,
    "team": null,
    "external_id": null,
    "position_title": null,
    "manager_first_name": null,
    "manager_last_name": null,
    "manager_external_id": null,
    "location": null,
    "country": null,
    "zip_code": null,
    "state_or_province": null,
    "department": "Engineering",
    "organization_level_1": "Farming",
    "organization_level_2": "Aquatic",
    "organization_level_3": "Kelp",
    "job_family": "f100",
    "bio": "Team-oriented leading edge capacity",
    "vanity_url": "http://localhost:5002/users/acclaim-owner",
    "badges": [
      {
        "id": "038f24de-6fe9-43de-b213-b36400d18b51",
        "issued_to": "Alfred Beaker Skiles",
        "issued_to_first_name": "Alfred",
        "issued_to_middle_name": "Beaker",
        "issued_to_last_name": "Skiles",
        "issued_at": "2014-04-01T14:41:00.000Z",
        "issued_at_date": "2014-04-01",
        "expires_at": "2016-04-01T14:41:00.000Z",
        "expires_at_date": "2016-04-01",
        "state": "pending",
        "public": false,
        "badge_template": {
          "id": "8b50d7fa-de1a-5073-8110-00ceb18d89dc",
          "image": null,
          "image_url": null,
          "description": "Dynamically deliver go forward e-tailers",
          "name": "Great GIF Finder",
          "skills": [
            "GIF Finding",
            "GIF Pronouncing",
            "GIF Sharing"
          ]
        },
        "issuer": {
          "name": "Acclaim",
          "image_url": null
        }
      }
    ]
  },
  "metadata": {
  }
}

Employee External Badges API

The Employee External Badges API allows employers to retrieve badges earned by their connected employees. External badges are defined as any badge not earned through the Credly platform.

Request

GET /organizations/<organization_id>/employee_external_badges

URL Parameters

Param Description
filter Filter the results. See Filtering below for details

Filtering

The filter parameter should use the following format: filter[employee][id].

Results can be filtered with the following keys:

Key Description
[employee][id] Can either be the value that is used by the employer to track employees or the UUID of the Employment record
[external_badge][type] Can either be OpenBadge or EmulatedBadge
[external_badge][verification_status][verified] Can be true or false

Paging

Results will be returned in pages. To retrieve the next page of results, make another request using the next_page_url returned in the metadata section of the response. When next_page_url is null, there are no more results to retrieve.

Response

This endpoint returns a collection of employees’ external badges that may contain badge formats that comply with Open Badge standards and/or badges that do not comply. The format is denoted by the type attribute in the response. The type attribute will indicate either "OpenBadge" or "EmulatedBadge". Clients can check the type field and handle each format as preferred.

Please note that only badges with the "OpenBadge" type can be confirmed by Credly at this time.

The following fields are present in badges with the "OpenBadge" type and not present in badges with the "EmulatedBadge" type: badge_criteria, issued_at, expires_at, credential_number, badge_version. The following field is present in badges with the "EmulatedBadge" type and not present in badges with the "OpenBadge" type: recipient_name.

200 OK

  {
  "data": [
    {
      "employee": {
        "id": "734ad131-78f0-4cb4-9819-c4c627c1ed5a",
        "external_id": null
      },
      "external_badge": {
        "type": "OpenBadge",
        "badge_name": "Leadership Principles",
        "badge_description": "Foundational leadership skills are essential to leadership success. Earners of this achievement are recognized for their commitment to leadership and have completed learning components, exhibited key attributes of successful leadership, and have contributed to the knowledge of their colleagues.",
        "issuer_name": "Pearson",
        "issued_at_date": "2012-11-09",
        "expires_at_date": "2016-04-01",
        "badge_url": "http://example.edu/credentials/0001",
        "badge_id": "http://example.edu/credentials/0001",
        "credly_record_id": "1c2f2ece-aee1-4e45-8e09-b13a1029b3c0",
        "refreshed_at": "2014-04-01T14:41:00.000Z",
        "skills": [
          {
            "name": "Skill 1"
          },
          {
            "name": "Skill 2"
          },
          {
            "name": "Skill 3"
          }
        ],
        "tags": [
          {
            "name": "Tag 1"
          },
          {
            "name": "Tag 2"
          },
          {
            "name": "Tag 3"
          }
        ],
        "credential_number": "12345",
        "badge_criteria": {
          "id": "http://example.edu/criterias/0001",
          "narrative": "Earners are required to exhibit foundational leadership skills."
        },
        "issued_at": "2012-11-09T00:59:17.000Z",
        "expires_at": "2016-04-01T14:41:00.000Z",
        "badge_version": "3.0",
        "verification_status": {
          "verified": false
        },
        "image_url": "https://cdn.example.com/path/to/image.png"
      }
    },
    {
      "employee": {
        "id": "734ad131-78f0-4cb4-9819-c4c627c1ed5a",
        "external_id": null
      },
      "external_badge": {
        "type": "EmulatedBadge",
        "badge_name": "Development Practices",
        "badge_description": "Foundational development practice skills are essential to developer success. Earners of this achievement are recognized for their commitment to development and have completed learning components, exhibited key attributes of successful development, and have contributed to the knowledge of their colleagues.",
        "issuer_name": "Organization 4",
        "issued_at_date": "2012-11-25",
        "expires_at_date": "2014-08-11",
        "badge_url": "https://example.org/badges/0001",
        "badge_id": "https://example.org/badges/0001",
        "credly_record_id": "0f440dc0-ecf6-4376-89c9-5807ff12af79",
        "refreshed_at": "2014-04-01T14:41:00.000Z",
        "skills": [
          {
            "name": "Skill 1"
          },
          {
            "name": "Skill 2"
          },
          {
            "name": "Skill 3"
          }
        ],
        "tags": [
          {
            "name": "Tag 1"
          },
          {
            "name": "Tag 2"
          },
          {
            "name": "Tag 3"
          }
        ],
        "recipient_name": "John Doe",
        "ai_influence": {
          "ai_influenced": false
        },
        "verification_status": {
          "verified": false
        },
        "image_url": "https://cdn.example.com/path/to/image.png"
      }
    }
  ],
  "metadata": {
    "next_page_url": null
  }
}

Employee Skills API

The Employee Skills API allows employers to retrieve skills that their employees have, along with the evidence in support of those skills. This list must be filtered by employee ID and by skill type.

Request

GET /organizations/<organization_id>/employee_skills

URL Parameters

Param Description
filter Filter the results. See Filtering below for details

Filtering

The filter parameter should use the following format: filter[employee][id] and filter[skill_type].

Results can be filtered with the following keys:

Key Description
[employee][id] Required. Can either be the value that is used by the employer to track employees or the UUID of the Employment record
[skill_type] Required. Must be PearsonOntology. In future, other skill types may be included in this API. The requirement to include the skill_type filter in all requests future-proofs your application against extensions to this API.

Paging

Results will be returned in pages. To retrieve the next page of results, make another request using the next_page_url returned in the metadata section of the response. When next_page_url is null, there are no more results to retrieve.

Response

This endpoint returns a collection of employees’ skills, sourced from their earned badges and their mapped occupation. Each skill can contain multiple evidence. The type attribute of the evidence will indicate either "BadgeSkillEvidence", "ExternalBadgeSkillEvidence", or "MappedOccupationSkillEvidence". Clients can check the type field and handle each format as preferred.

We may add new types of skill evidence in the future. When building an integration, we suggest discarding evidence items that have an unknown type (optionally combined with logging or recording an error) to avoid interruptions when a new evidence type becomes available.

note: MappedOccupationSkillEvidence requires use of the Unified Platform to map employees to occupations. If you are unsure whether your organization uses the Unified Platform, you can contact Credly Support at https://support.credly.com/hc/en-us/requests/new

200 OK

  {
  "data": [
    {
      "employee": {
        "id": "734ad131-78f0-4cb4-9819-c4c627c1ed5a",
        "external_id": "987654321"
      },
      "skill": {
        "skill": {
          "name": "Cooperation"
        },
        "evidence": [
          {
            "type": "BadgeSkillEvidence",
            "badge": {
              "id": "892a07b9-af03-4d8d-a113-6daae9acd451",
              "badge_url": "https://example.com/badges/892a07b9",
              "issued_at": "2025-06-02T04:00:00.000Z",
              "issued_at_date": "2025-06-02",
              "expires_at": null,
              "expires_at_date": null,
              "badge_template": {
                "id": "ed17c0b0-6bf0-4a49-b9b8-0de66fcf0431",
                "name": "Basics of Cooperation"
              },
              "issuer": {
                "name": "Sample Organization",
                "photo": {
                  "image_url": "https://example.com/badges/images/21d15be1/600x600.png"
                }
              }
            }
          }
        ]
      }
    },
    {
      "employee": {
        "id": "734ad131-78f0-4cb4-9819-c4c627c1ed5a",
        "external_id": "987654321"
      },
      "skill": {
        "skill": {
          "name": "Written Communication Skills"
        },
        "evidence": [
          {
            "type": "ExternalBadgeSkillEvidence",
            "external_badge": {
              "type": "OpenBadge",
              "badge_name": "Making Butterflies",
              "badge_description": "Libero tenetur saepe. Velit nesciunt facilis. Quidem et eligendi.",
              "issuer_name": "Cummerata, Beier and Kub",
              "issued_at_date": "2023-08-28",
              "expires_at_date": null,
              "badge_url": "http://example.edu/credentials/0001",
              "badge_id": "http://example.edu/credentials/0001",
              "credly_record_id": "794e5e55-0330-4540-9eae-d50f7ac54199",
              "refreshed_at": "2025-05-27T19:31:37.028Z",
              "skills": [
                {
                  "name": "Written Communication Skills"
                },
                {
                  "name": "Written Communication Skills"
                }
              ],
              "tags": [
                {
                  "name": "Ad occaecati doloribus dolor."
                },
                {
                  "name": "Rem consequatur sunt architecto."
                },
                {
                  "name": "Dolorem nihil eos sequi."
                },
                {
                  "name": "Suscipit et nihil odit."
                }
              ],
              "credential_number": "37a8f907-511f-4c53-9837-49adc4319fd4",
              "badge_criteria": {
                "id": "http://example.edu/criterias/0001",
                "narrative": "Et ipsa iure. Aut sit eos. Dolorum nihil adipisci."
              },
              "issued_at": "2023-08-28T21:46:15.000Z",
              "expires_at": null,
              "badge_version": "3.0",
              "verification_status": {
                "verified": false
              },
              "image_url": "http://example.com/images/a9d9c8e1-99b2-473e-9d0b-4afea32fa211/badge.svg"
            }
          },
          {
            "type": "MappedOccupationSkillEvidence",
            "occupation": {
              "code": "FS100",
              "name": "Software Developer"
            }
          }  
        ]
      }
    }
  ],
  "metadata": {
    "next_page_url": null
  }
}