Workforce

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 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",
      "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,
      "country": null,
      "zip_code": null,
      "state_or_province": null,
      "department": null
    }
  ],
  "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",
    "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,
    "country": null,
    "zip_code": null,
    "state_or_province": null,
    "department": null
  },
  "metadata": {
  }
}

Create an Employee

Request

POST /organizations/<organization_id>/employees

Parameters

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
managerfirstname	Employee manager's first name
managerlastname	Employee manager's last name
managerexternalid	Employee manager's internal id used from employer if used
country	Employee country
zip_code	Employee zip code
stateorprovince	Employee state or province (US/CA)
department	Employee department

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",
  "country": "United States of America",
  "zip_code": "55347",
  "state_or_province": "Minnesota"
}

Response

201 Created

{
  "data": {
    "id": "8ab46f92-28bb-4c77-a423-1b698923cc81",
    "email": "email1@example.com",
    "created_at": "2014-04-01T14:41:00.000Z",
    "employee_state": "pending",
    "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": null,
    "country": "United States of America",
    "zip_code": "55347",
    "state_or_province": "Minnesota",
    "department": null
  },
  "metadata": {
  }
}

Update an Employee

Request

PUT /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

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
managerfirstname	Employee manager's first name
managerlastname	Employee manager's last name
managerexternalid	Employee manager's internal id used from employer if used
country	Employee country
zip_code	Employee zip code
stateorprovince	Employee state or province (US/CA)
department	Employee department

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",
  "country": "United States of America",
  "zip_code": "55347",
  "state_or_province": "Minnesota"
}

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",
    "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": null,
    "country": "United States of America",
    "zip_code": "55347",
    "state_or_province": "Minnesota",
    "department": null
  },
  "metadata": {
  }
}

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",
    "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,
    "country": null,
    "zip_code": null,
    "state_or_province": null,
    "department": null,
    "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": {
  }
}