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: 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	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": "4734c163-6150-49d2-b366-65ff17752e33",
    "email": "email1@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": "https://www.credly.com/users/acclaim-owner",
    "badges": [
      {
        "id": "e3e00f1d-84a3-41b4-82a9-fa794ea7158c",
        "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",
        "expires_at": "2016-04-01T14:41:00.000Z",
        "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": {
  }
}