Privacy Bee Developers

Contacts

Search Alt+S

Manage the contacts of a logged in user. This could be family members, friends, or other trusted people.

GET /contacts
GET /contacts/<id>
POST /contacts
DELETE /contacts/<id>
PUT /contacts/<id>
GET /contacts/requests
POST /contacts/trust/<id>
D EL /contacts/clear
GET /contacts/employees

Table of Contents

GET /contacts
GET /contacts/< id>
POST /contacts
DELETE /contacts/< id>
PUT /contacts/< id>
GET /contacts/requests
POST /contacts/trust/
DEL /contacts/clear
GET /contacts/employees

GET /contacts

Returns a JSON object of all the authenticated user’s contacts

Parameters:

Variable	Data Type	Default	Required	Description
`updated_at`	`timestamp`	`null`	No	If passed, only returns Contacts that have been created or updated on or since the timestamp (UTC).
`page`	`integer`	`1`	No	For pagination, which page number you want returned
`per_page`	`integer`	`10`	No	Number of results per page you want
`include`	`string`	`null`	No	A comma separated list of the related data you want. Options are: “`emails`” “`addresses`” “`phone_numbers`“ Example: `&include=emails,addresses,phone_numbers`

Example Request

curl -X GET "https://api.privacybee.com/contacts?updated_at=2023-01-01T00:00:00Z&page=1&per_page=10&include=emails,addresses,phone_numbers" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}"

Return: A JSON array of Contact objects

Example

[
    {
        "id": 647dccb3a16b7,
        "profile_icon": "https://cdn.privacybee.com/...",
        "display_name": "Beth M.",
        "birthday": "1975-11-24",
        "email": ["bethm@privacybee.com", "beth.m@example.com"],
        "phone": ["+12385551629", "+12384152637", "+12374151432"],
        "address": [
            "123 ABC, Apartment 14, Alpharetta, GA, 30005, US",
            "123 Peachtree St, Apartment 132, Atlanta, GA, 30303, US"
        ],
        "risk_score": 92,
        "labels": ["Client", "Newsletter Subscriber"],
        "user_id": 54198486,
        "e2ee": true,
        "created": "2023-02-10",
        "updated": "2023-07-15"
    },
    {
        "id": 647dccb3a16b8,
        "profile_icon": "https://cdn.privacybee.com/...",
        "display_name": "John D.",
        "birthday": "1980-05-14",
        "email": ["johnd@privacybee.com", "john.d@example.com"],
        "phone": ["+12385551630", "+12384152638", "+12374151433"],
        "address": [
            "456 DEF, Apartment 20, Alpharetta, GA, 30005, US",
            "456 Peachtree St, Apartment 140, Atlanta, GA, 30303, US"
        ],
        "risk_score": 85,
        "labels": ["Partner", "VIP"],
        "user_id": 54198487,
        "e2ee": true,
        "created": "2023-03-12",
        "updated": "2023-07-16"
    }
]

GET /contacts/<id>

Returns a JSON object of the Contact by the search ID, if it exists and the authenticated user has proper permissions

Example Request

curl -X GET "https://api.privacybee.com/contacts/12345" \
     -H "Authorization: Bearer {access_token}"

Example Response

{
    "id": 64767898,
    "profile_icon": "https://cdn.privacybee.com/...",
    "display_name": "Beth M.",
    "birthday": "1975-11-24",
    "email": ["bethm@privacybee.com", "beth.m@example.com"],
    "phone": ["+12385551629", "+12384152637", "+12374151432"],
    "address": [
        "123 ABC, Apartment 14, Alpharetta, GA, 30005, US",
        "123 Peachtree St, Apartment 132, Atlanta, GA, 30303, US"
    ],
    "risk_score": 92,
    "labels": ["Client", "Newsletter Subscriber"],
    "user_id": 54198486,
    "e2ee": true,
    "created": "2023-02-10",
    "updated": "2023-07-15"
}

POST /contacts/sync

Pass in an array of Contact objects to sync. If an id is included it will update an existing contact, if no id is included it will create a new contact

Note: Only non-system fields are settable. Field: risk_score, profile_icon, connected, e2ee, created, and updated are read-only.

Example Request

curl -X POST "https://api.privacybee.com/contacts/sync" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \ 
     -d '[
           {
             "id": "12345",
             "display_name": "John Doe",
             "emails": [
               "john.doe@example.com"
             ],
             "addresses": [
               "123 Main St, Anytown, USA"
             ],
             "phone_numbers": [
               "+1234567890"
             ]
           },
           {
             "display_name": "Jane Smith",
             "emails": [
               "jane.smith@example.com"
             ],
             "addresses": [
               "456 Elm St, Othertown, USA"
             ],
             "phone_numbers": [
               "+0987654321"
             ]
           }
         ]'

Return: HTTP/200 OK if PUT was successful, or an error message if any issues occurred.

DELETE /contacts/<id>

Delete a Contact by ID (assuming the authenticated user has appropriate permissions). Note, there is no confirmation or double-check, as that should be handled by the frontend or client app. This action is permanent and irreversible.

Example Request

curl -X DELETE "https://api.privacybee.com/contacts/12345" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}"

Return: HTTP/200 OK if DELETE was successful, or an error message if any issues occurred.

PUT /contacts/<id>

Pass in an a Contact object to update the contact with the specified ID.

Example Request

curl -X PUT "https://api.privacybee.com/contacts/12345" \
     -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
           "display_name": "John Doe",
           "emails": [
             "john.doe@example.com"
           ],
           "addresses": [
             "123 Main St, Anytown, USA"
           ],
           "phone_numbers": [
             "+1234567890"
           ],
           "birthday": "1975-11-24",
           "labels": [
             "Client", "Newsletter Subscriber"
           ]
         }'

GET /contacts/requests

Returns a list of pending trust requests.

Example Request

curl -X GET "https://api.privacybee.com/contacts/requests" \
      -H "Authorization: Bearer ${ACCESS_TOKEN}"

Return: Returns a list of pending trust requests with the following fields:

Field	Data Type	Description
`id`	`unsigned integer`	The ID of the person requesting trust
`first_name`	`string`	Users first name
`middle_name`	`string`	Users middle name
`last_name`	`string`	Users last name
`contact_reason`	`string`	The reason given from this contact as to why they want to contact them
`updated_at`	`timestamp`	When this contact was last updated

Example

[
  {
    "id": 12345,
    "first_name": "John",
    "middle_name": "A.",
    "last_name": "Doe",
    "contact_reason": "Business Inquiry",
    "updated_at": "2024-07-31T12:34:56Z"
  },
  {
    "id": 67890,
    "first_name": "Jane",
    "middle_name": "B.",
    "last_name": "Smith",
    "contact_reason": "Networking",
    "updated_at": "2024-07-30T11:22:33Z"
  }
]

POST /contacts/trust/<id>

Use this endpoint to trust or not trust a person from the results of the trust-requests GET

Parameters: Returns a list of pending trust requests

Field	Data Type	Description
`trusted`	`boolean`	`1` if we want to trust, `0` if we want to untrust

Example Request

curl -X POST "https://api.privacybee.com/contacts/trust/12345" \
     -H "Authorization: Bearer ACCESS_TOKEN"
     -H "Content-Type: application/json" \
     -d '{"trusted": 1}'

Return: The 201 Created status code indicates that the request has been fulfilled and has resulted in the creation of a new resource. In the context of the POST /contacts/trust/{id} endpoint, it means that the trust status of the contact has been successfully updated.

DELETE /contacts/clear/<id>

Note: This endpoint is intended for removing all contacts and should be used only during development.

Example Request

curl -X DELETE "https://api.privacybee.com/contacts/clear/12345" \
      -H "Authorization: Bearer Bearer ${ACCESS_TOKEN}"

GET/contacts/employees/<id>

This endpoint will return all companies a person belongs to as well as any employees from each company

Example Request

curl -X GET "https://api.privacybee.com/contacts/employees/<id>" -H "Accept: application/json"

Return: The return will include an array of objects. Each object will have a company key which will have the data about a company and then a key of employees which will be an array of employee objects containing the various employees of that company.

Field	Data Type	Description
`*.company`	`array`	the `id` , `name` , `slug` , `logo`, and `URL` of the company
`*.employees`	`array<object>`	the `id` , `first_name` , and `last_name` of employees of the company

Example

[
    {
        "company": {
            "id": "123",
            "name": "Tech Innovators", 
            "slug": "tech-innovators",
            "logo": "https://example.com/logos/tech-innovators.png",
            "url": "https://techinnovators.com"
        },
        "employees": [
            {
                "id": "1",
                "first_name": "John",
                "last_name": "Doe"
            },
            {
                "id": "2",
                "first_name": "Jane",
                "last_name": "Smith"
            }
        ]
    },
    {
        "company": {
            "id": "456",
            "name": "Creative Solutions",
            "slug": "creative-solutions",
            "logo": "https://example.com/logos/creative-solutions.png",
            "url": "https://creativesolutions.com"
        },
        "employees": [
            {
                "id": "3",
                "first_name": "Alice",
                "last_name": "Johnson"
            },
            {
                "id": "4",
                "first_name": "Bob",
                "last_name": "Brown"
            }
        ]
    }
]

v3.0.1 Current

v2.1.5 Deprecated

Contacts

GET /contacts

Parameters:

GET /contacts/<id>

POST /contacts/sync

DELETE /contacts/<id>

PUT /contacts/<id>

GET /contacts/requests

POST /contacts/trust/<id>

DELETE /contacts/clear/<id>

GET/contacts/employees/<id>

GET /contacts

Parameters:

GET /contacts/<id>

POST /contacts/sync

DELETE /contacts/<id>

PUT /contacts/<id>

GET /contacts/requests

POST /contacts/trust/<id>

DELETE /contacts/clear/<id>

GET/contacts/employees/<id>

Start typing to search