API docs

Appearance

On this page

Contacts ​

Endpoints ​

GET /v1/contacts
GET /v1/contacts/:id
POST /v1/contacts
PATCH /v1/contacts/:id
DELETE /v1/contacts/:id

INFO

GET endpoints are available for all API users. However, POST, PATCH, and DELETE endpoints are only available if you are using the API as your sync source. If you are using a sync source other than the API to sync your employee data to Workshop, you can only use the GET endpoints.

List contacts ​

GET /v1/contacts

Returns a list of contacts.

Parameters ​

NameOptionalDefaultDescriptionOptions
Pagination parametersSee pagination for more information.

RETURNS ​

A paginated list of contact summary objects.

EXAMPLE RESPONSE ​

json
{
  "object": "list",
  "has_more": true,
  "next": "/v1/contacts?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "contact",
      "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "external_id": "ABC-123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone_number": "+12345678910",
      "urls": {
        "details": "/v1/contacts/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

Retrieve a contact ​

GET /v1/contacts/:id

Gets the details of a single contact.

Parameters ​

NameOptionalTypeDescription
idrequiredstringThe ID of the contact to retrieve.

RETURNS ​

A contact object.

EXAMPLE RESPONSE ​

json
{
  "object": "contact",
  "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
  "external_id": "ABC-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "+12345678910",
  "attributes": {
    "department": "Sales",
    "office": "Austin"
  },
  "urls": {
    "details": "/v1/contacts/937ccbe2-4cb5-4c76-96bf-29510b514dfa"
  }
}

Create a contact ​

POST /v1/contacts

Creates a new contact.

Parameters ​

NameOptionalTypeDescription
external_idrequiredstringA unique identifier from your system for the contact.
first_namerequiredstringThe first name of the contact.
last_namerequiredstringThe last name of the contact.
emailrequiredstringThe email address of the contact.
phone_numberoptionalstringThe phone number of the contact.
attributesoptionalobjectA dictionary of attributes for the contact.

EXAMPLE PAYLOAD ​

json
{
  "external_id": "ABC-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "+12345678910",
  "attributes": {
    "department": "Sales",
    "office": "Austin"
  }
}

RETURNS ​

A success message and a 201 status code if successful.

ERRORS ​

CodeDescription
400Invalid request, missing required parameters or supplied parameters are invalid
409Contact with the same external_id already exists

EXAMPLE RESPONSE ​

json
{
  "message": "Contact created successfully"
}

Update a contact ​

PATCH /v1/contacts/:id

Updates a contact.

Parameters ​

NameOptionalTypeDescription
idrequiredstringThe ID of the contact to update.
external_idoptionalstringA unique identifier from your system for the contact.
first_nameoptionalstringThe first name of the contact.
last_nameoptionalstringThe last name of the contact.
emailoptionalstringThe email address of the contact.
phone_numberoptionalstringThe phone number of the contact.
attributesoptionalobjectA dictionary of attributes for the contact.

If you do not supply a parameter, its value will remain unchanged. If you attempt to update a contact that does not currently have an external_id, you must supply an external_id value in your request. If attributes is supplied, it will replace the existing attributes for the contact, not merge them.

EXAMPLE PAYLOAD ​

json
{
  "first_name": "John",
  "last_name": "Doe"
}

RETURNS ​

A success message and a 200 status code if successful.

ERRORS ​

CodeDescription
400Invalid request, supplied parameters did not pass validation.
404Contact with the given ID was not found.

EXAMPLE RESPONSE ​

json
{
  "message": "Contact updated successfully"
}

Delete a contact ​

DELETE /v1/contacts/:id

Deletes a contact.

Parameters ​

NameOptionalTypeDescription
idrequiredstringThe ID of the contact to delete.

RETURNS ​

A success message and a 200 status code if successful.

EXAMPLE RESPONSE ​

json
{
  "message": "Contact deleted successfully"
}