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 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
  }
}