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 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 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": {
}
}