Employees
Alt+S
Don’t forget to include your authentication with each request. All results will return a JSON object with a meta field, containing system information about the query.
- GET /employees
- GET /employees/<id>
- POST /employees
- PUT /employees/<id>
- GET /employees/exposures
- DELETE /employees/<id>
- GET /employees/exposures/<id>
GET /employees
Returns a JSON object of all employees within the company.
Parameters:
| Variable | Data Type | Default | Required | Description |
|---|---|---|---|---|
search | string | null | No | This allows the searching of employees by email address. The filter is set so that it will always search starting at the beginning of the email “{SEARCH}%“. |
Example Request
curl -X GET "https://api.privacybee.com/companies/{{COMPANY_ID}}/employees" -H "Accept: application/json"
Return: A JSON array of Person objects
Example
[
{
"id": 74980364,
"first_name": "Eduard",
"middle_name": "Gabriel",
"last_name": "Bettley",
"display_name": "Eduard Gabriel Bettley",
"dob": "1975-11-24",
"akas": [
{
"id": 3,
"first_name": "Ed",
"middle_name": null,
"last_name": "Bettley"
}
],
"addresses": [
{
"id": 1,
"primary": true,
"line_1": "123 ABC Street",
"line_2": null,
"city": "Atlanta",
"region": "GA",
"postal_code": "30005",
"country": "US"
}
],
"emails": [
{
"id": 1,
"primary": true,
"email": "employee@company.com"
}
],
"phone_numbers": [
{
"id": 1,
"primary": true,
"country_code": "1",
"phone_number": "5551234567",
"phone_full": "+15551234567"
}
],
"last_scan_at": "2024-04-26T00:00:00Z",
"license": {
"type": "complete",
"price": 19700,
"start_date": "2024-10-07T00:00:00Z",
"end_date": "2025-10-07T00:00:00Z",
"renews": 1,
"prorate_on_renewal": 0
},
"roles": [
"HR Manager",
"Consultant"
],
"risk_score": 62,
"exposures": {
"total": 30,
"pending": 15,
"in_progress": 10,
"closed": 2,
"not_found": 3
},
"last_login": "2024-04-27T08:28:15Z",
"created_at": "2024-04-26T00:00:00Z"
}
]
GET /employees/<id>
Returns the details of an employee with the specified ID.
Parameters:
| Variable | Data Type | Required | Description |
|---|---|---|---|
id | unsigned integer | Yes | The unique identifier for the employee. |
Example Request
curl -X GET "https://api.privacybee.com/companies/{{COMPANY_ID}}/employees/123" -H "Accept: application/json"
Return: Person object
Example
{
"id": 74980364,
"first_name": "Eduard",
"middle_name": "Gabriel",
"last_name": "Bettley",
"display_name": "Eduard Gabriel Bettley",
"dob": "1975-11-24",
"akas": [
{
"id": 3,
"first_name": "Ed",
"middle_name": null,
"last_name": null
}
],
"addresses": [
{
"id": 1,
"primary": true,
"line_1": "123 ABC Street",
"line_2": null,
"city": "Atlanta",
"region": "GA",
"postal_code": "30005",
"country": "US"
}
],
"emails": [
{
"id": 1,
"primary": true,
"email": "employee@company.com"
}
],
"phone_numbers": [
{
"id": 1,
"primary": true,
"country_code": "1",
"phone_number": "5551234567",
"phone_full": "+15551234567"
}
],
"last_scan_at": "2024-04-26T00:00:00Z",
"license": {
"type": "complete",
"price": 19700,
"start_date": "2024-10-07T00:00:00Z",
"end_date": "2025-10-07T00:00:00Z",
"renews": 1,
"prorate_on_renewal": 0
},
"roles": [
"HR Manager",
"Consultant"
],
"risk_score": 62,
"exposures": {
"total": 30,
"pending": 15,
"in_progress": 10,
"closed": 2,
"not_found": 3
},
"last_login": "2024-04-27T08:28:15Z",
"created_at": "2024-04-26T00:00:00Z"
}
POST /employees
Create a new employee within this company, or error if their primary email already exists as an existing employee.
Best Practices
When creating or updating an employee, any values passed in will be automatically standardized, however you can minimize issues by adhering to these best practices:
- Email addresses should be lowercase and without any + notation
- US address should be as close to CASS standardized as possible and should use a two character state code (ex:
CA,GA,TX,NY) - Country code should always be a two character standard (ex:
US,CA,UK,IE)
Parameters:
| Variable | Data Type | Default | Required | Description |
|---|---|---|---|---|
first_name | string | Yes | First name | |
middle_name | string | null | No | Middle name |
last_name | string | Yes | Last name | |
emails | Array[Email] | Yes | Employee email addresses | |
dob | date(y-m-d) | Yes | Date of birth | |
akas | Array[Aka] | No | Alternate names of person | |
phone_numbers | Array[Phone] | null | No | Employee phone numbers |
addresses | Array[Address] | Yes | Employee addresses | |
roles | Array<string> | ["HR"] | No | What role(s) within the business does this employee hold? |
license | license_id | scan | No | Which license should this employee be granted? |
invite | boolean | No | Should they receive an invite email to login | |
ephemeral | boolean | No | Create this person as ephemeral (will be deleted 24 hours) |
Example Request
curl -X POST https://api.privacybeee.com/companies/{{COMPANY_ID}}/employees \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"middle_name": "A",
"last_name": "Doe",
"akas": [
{
"first_name": "Jonathon"
}
],
"addresses": [
{
"id": 1,
"primary": true,
"line_1": "123 ABC Street",
"line_2": null,
"city": "Atlanta",
"region": "GA",
"postal_code": "30005",
"country": "US"
}
],
"emails": [
{
"id": 1,
"primary": true,
"email": "employee@company.com"
}
],
"phone_numbers": [
{
"id": 1,
"primary": true,
"country_code": "1",
"phone_number": "5551234567",
"phone_full": "+15551234567"
}
],
"dob": "1990-01-01",
"roles": ["Engineer"],
"license": "scan",
"invite": true
}'
Return: Person object.
If the employee creation is successful, HTTP/200 Success status code will be returned. Otherwise if the Employee could not be created (such as if the email already exists), or there’s a data issue with the request, HTTP/400 Bad Request will be returned. Depending on the failure, the response body might include a JSON error object with additional details.
{
"id": 74980364,
"first_name": "Eduard",
"middle_name": "Gabriel",
"last_name": "Bettley",
"display_name": "Eduard Gabriel Bettley",
"dob": "1975-11-24",
"akas": [
{
"first_name": "Jonathon"
}
],
"addresses": [
{
"id": 1,
"primary": true,
"line_1": "123 ABC Street",
"line_2": null,
"city": "Atlanta",
"region": "GA",
"postal_code": "30005",
"country": "US"
}
],
"emails": [
{
"id": 1,
"primary": true,
"email": "employee@company.com"
}
],
"phone_numbers": [
{
"id": 1,
"primary": true,
"country_code": "1",
"phone_number": "5551234567",
"phone_full": "+15551234567"
}
],
"last_scan_at": "2024-04-26T00:00:00Z",
"license": {
"type": "complete",
"price": 19700,
"start_date": "2024-10-07T00:00:00Z",
"end_date": "2025-10-07T00:00:00Z",
"renews": 1,
"prorate_on_renewal": 0
},
"roles": [
"HR Manager",
"Consultant"
],
"risk_score": 62,
"exposures": {
"total": 15,
"pending": 0,
"in_progress": 0,
"closed": 0,
"not_found": 10
},
"last_login": "2024-04-27T08:28:15Z",
"created_at": "2024-04-26T00:00:00Z"
}
PUT /employees/<id>
Updates an existing employee based on the ID in the request URL. Include only the fields you wish to update.
| Variable | Data Type | Required | Description | Example |
|---|---|---|---|---|
first_name | string | No | First name | |
middle_name | string | No | Middle name | null |
last_name | string | No | Last name | |
email | Array[Email] | No | Employee emails | |
dob | date(y-m-d) | No | Date of birth | |
akas | Array[Aka] | No | Alternate names of person. If empty array supplied it will remove all. Otherwise the payload will replace all existing, so always include all or do not include at all | |
phone_numbers | Array[Phone] | No | Employee phone numbers. If empty array supplied all numbers will be removed. Otherwise the payload will replace all existing, so always include all or do not include at all | null |
addresses | Array[Address] | No | If empty array supplied all addresses will be removed. Otherwise the payload will replace all existing, so always include all or do not include at all | null |
roles | Array<string> | No | What role(s) within the business does this employee hold? | ["HR"] |
license | string | No | Name of the license to give to the person if they do not already have one, will change license if a different one is specified | complete |
Example Request
curl -X PUT https://api.privacybee.com/companies/{{COMPANY_ID}}/employees/12345 \
-H "Content-Type: application/json" \
-d '{
"first_name": "Employee",
"middle_name": null,
"last_name": "Name",
"dob": "1963-12-08",
"phone_numbers": [
{
"primary": true,
"country_code": 1,
"phone_number": 5552341111
}
],
"emails": [
{
"primary": true,
"email": "employee@company.com"
}
],
"addresses": [
{
"primary": true,
"line_1": "12020 Leeward Walk",
"city": "Alpharetta",
"region": "Georgia",
"country": "US"
},
]
}'
Return: Person object
DELETE /employees/<id>
This will remove a person with the specified ID from your company.
Note: When an employee is removed and their account contains only employee emails (i.e., they have not added personal emails), their account is completely removed from the system. However, if an employee has added their own emails to their account, only the employer emails will be removed, resulting in the employee no longer being connected to the employer. Despite this, their account will continue to exist.
Parameters:
| Variable | Data Type | Required | Description |
|---|---|---|---|
id | unsigned integer | Yes | The unique identifier of the person to be deleted. |
Example Request
curl -X DELETE https://api.privacybee.com/companies/{{COMPANY_ID}}/employees/74980364 \
-H "Content-Type: application/json"
Return: 204 No Content. This status code indicates that the operation was successful, but there is no content to return.
GET /employees/exposures
This is the primary endpoint to get updates on the status of exposures for employees, using this you can get the current status, recent actions, and data found across the scans of your employees.
Parameters:
| Variable | Data Type | Default | Required | Description |
|---|---|---|---|---|
since | timestamp | null | No | If null, returns all exposures. If a UTC timestamp is set, only exposures that have changed at or since that timestamp will be returned, such as new exposures or status updates. |
employees | string | null | No | Comma separated list of employee ids to filter the results. |
status | string | null | No | Can pass "pending" , "in_progress" or "closed" or a comma separated list of multiple to filter the exposures based on their current status. |
exposed | boolean | true | No | If true, the results will only include exposures that are currently exposed. |
Example Request
curl -X GET "https://api.privacybee.com/companies/{{COMPANY_ID}}/employees/exposures?since=2024-01-01T00:00:00Z&employees=123,456&status=pending,in_progress&exposed=true" \
-H "Content-Type: application/json"
Return: A JSON array of Exposures, spanning all requested employees.
GET /employees/exposures/<id>/history
Get the full history of all actions taken on a particular exposure.
Parameters: ID of the exposure.
| Variable | Data Type | Required | Description |
|---|---|---|---|
id | unsigned integer | Yes | The unique identifier for a particular exposure. |
Example Request
curl -X GET https://api.privacybee.com/companies/{{COMPANY_ID}}/employees/{{EXPOSURE_ID}}/\
-H "Content-Type: application/json"
[
{
"event": "Privacy request was created and will be submitted soon.",
"company": {
"id": 19459,
"name": "freepeopledirectory.com",
"slug": "freepeopledirectorycom",
"logo": "https://cdn.privacybee.com/company-logo/local/7.png",
"url": "freepeopledirectory.com"
},
"when": "2024-10-07T17:23:51Z"
},
{
"event": "Your privacy request has been closed.",
"company": {
"id": 19459,
"name": "freepeopledirectory.com",
"slug": "freepeopledirectorycom",
"logo": "https://cdn.privacybee.com/company-logo/local/7.png",
"url": "freepeopledirectory.com"
},
"when": "2024-10-07T17:23:51Z"
}
]
Privacy Bee, LLC. © Copyright 2026. All Rights Reserved.