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: key::value
. You can combine keys for stricter searches, e.g. state::accepted|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 |
team |
Matches employees who are on a specific team |
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 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 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 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 endpoint will allow employers to retrieve external (not issued through Credly) badges earned by employees.
Request
GET /organizations/<organization_id>/employee_external_badges
URL Parameters
Param | Description |
---|---|
page |
Gets the specified page of employees |
per |
Determines how many employees to include on a page |
Filtering
The filter
parameter has the following format: filter[employee][id]
.
Results can be filtered with the following keys:
Key | Description |
---|---|
[employee][id] |
Can either be the Id value that is used by the employer to internally track employees or the UUID of the Employment record |
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": [
{
"employee": {
"id": "377f7425-bd03-418b-92af-ea20219fd6e6",
"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.",
"credential_number": "12345",
"badge_criteria": {
"id": "https://example.edu/criterias/0001",
"narrative": "Earners are required to exhibit foundational leadership skills."
},
"issuer_name": "Pearson",
"issued_at": "2023-04-01T13:12:40.000Z",
"issued_at_date": "2023-04-01",
"expires_at": "2025-04-01T13:12:40.000Z",
"expires_at_date": "2025-04-01",
"badge_url": "https://example.edu/credentials/0001",
"badge_id": "https://example.edu/credentials/0001",
"credly_record_id": "fba9a90b-fc8d-48c6-9ebd-b4ea0a4e86ef",
"refreshed_at": "2024-09-04T03:33:36.455Z",
"skills": [
{
"name": "Skill 1"
},
{
"name": "Skill 2"
},
{
"name": "Skill 3"
}
],
"verification_status": {
"verified": false
},
"image_url": "https://cdn.example.com/path/to/image.png"
}
}
],
"metadata": {
"count": 1,
"current_page": 1,
"total_count": 1,
"total_pages": 1,
"per": 50,
"previous_page_url": null,
"next_page_url": null
}
}