# The Clockwork API

Welcome to the Clockwork API! Here you'll find all the ways you can interact with the Clockwork ecosystem programmatically

## Getting Started

In order to use the Clockwork API, you'll need an API token. Contact us for one. Once you have it, it'll look something like this: `WHICv_xM.SFMyNTY.g3QAAAACZAAEZGF0YWEBZAAGc2lnbmVkbgYA21AjlnIB.J2z-zY3HYRBoKOwGI-qZkfAmChlC4lO9HxxJ_u5RlIA`

In order to make requests to the API, you'll need to put your API token in your request `Authorization` header. It'll look something like this:

```
{
    "Authorization": "Bearer <api_token>"
}
```

Once that's set up, you're ready to start using the API!

## Create/Update customer

<mark style="color:green;">`POST`</mark> `https://app.clockworkhq.com/api/v1/customers`

This endpoint allows you to create or update a customer. We key each customer by the email address supplied in the body parameters. If a customer already exists, we will update their name (first and last), and their attributes

#### Headers

| Name          | Type   | Description                                                         |
| ------------- | ------ | ------------------------------------------------------------------- |
| Authorization | string | Api authentication token. Should be in the form of Bearer: \<token> |

#### Request Body

| Name        | Type   | Description                                                                                                                      |
| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| email       | string |                                                                                                                                  |
| full\_name  | string | <p>The customer's full name as a single<br>string, e.g. "Brønt Chloaf." We will parse this out as first\_name and last\_name</p> |
| first\_name | string | The customer's first name                                                                                                        |
| last\_name  | string | The customer's last name                                                                                                         |

{% tabs %}
{% tab title="200 Customer successfully created or updated" %}

```
{message: "Success"}
```

{% endtab %}

{% tab title="401 This usually means the API key was invalid or not found in the request headers" %}

```
{"message": "Could not validate - API key may be malformed or invalid"}
```

{% endtab %}

{% tab title="500 Something bad happened on our end :(" %}

```
{"message": "Error - customer was not created. Reason: <error_reason>"}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Any additional parameters you add to the body other than `first_name, last_name, full_name,` and `email` will be automatically added to the list of the customer's attributes.
{% endhint %}


# Outgoing Webhooks

## Introduction

Outgoing webhooks enable an external application (controlled by you) to be notified when an event happens within the Clockwork ecosystem. Examples include when an invitation email is sent to a customer, or when a new study is launched.

Once you have subscribed to an event, we will send an HTTP `post` request to a URL that you supply, with an attached payload of metadata about the event

## List of Webhooks supported

Currently, the only events we support for outgoing webhooks are:

`invitation_sent`- Triggered when an appointment invitation email is created and sent

The payload for `invitation_sent`:

```
event_name - The name of the webhook
uuid - The unique identifier for this webhook in Clockwork
sub_uuid - The unique identifier for your instance of this webhook in Clockwork
customer_uuid - The unique identifier for this customer in Clockwork
customer_email - The email of the customer
customer_first_name - The customer's first name
customer_last_name - The customer's last name
customer_attributes - The current list of all attributes of the customer
customer_last_contacted_at - A timestamp of when the customer was last contacted
```

## Example

Let's say you want to use the `invitation_sent` webhook. First, you would contact us and let us know the name of the event (`invitation_sent`), and the URL where we should send the event, e.g. `https://youdomain.com/webhooks/webhook_name`. Once set up, you'll start receiving `POST` requests to the url you specified, with the payload that was detailed above.


# Frequently Asked Questions

***How do I upload user data into Clockwork?***

You can easily add new user data through our CSV uploader or the API. Please reach out to us for BETA API access.

***Can we segment customers in Clockwork and outreach to specific groups of users?***

Yes, we allow for sophisticated customer segmentation that will allow you to find the right group of users to engage with at the right time.

***Will Clockwork blast our whole customer list?***

No, Clockwork's algorithms will send emails out in timed batches based on your study criteria to make sure we don't annoy your customers.

***When does Clockwork actually engage our customers?***

Your customers will only be contacted during work hours 10am - 5pm in local time for your customers.

***Can we reschedule or cancel scheduled appointments using Clockwork?***

Yes, there are rescheduling and cancel appointment links available on the calendar invites and in the confirmation emails.

***Is it possible to accidentally contact the same customer in two different studies?***

No. Once a customer has been contacted, Clockwork will not be able to reach out to the same customer again for a certain period of time. The current default Do Not Contact time setting is 60 days.

***Is it possible to know when a customer was last contacted?***

Yes. Clockwork automatically tracks the last date of contact and the number of times a customer has been contacted and is visible to everyone on your team.

***What are the available Clockwork variables to use when creating recruiting and reminder emails?***

```
Variables relating to your customers:
{{first_name}} 
{{last_name}} 

Variables relating to the study leader in Clockwork:
{{my_company_name}} 
{{my_first_name}} 
{{my_last_name}} 
{{my_job_title}} 
{{my_company_name}}

Variables related to scheduling in Clockwork:
{{scheduling_link}}
```

## Bonus: Best Practice Tips

> **Find your baseline first** - Use your initial study to get familiar with our tool and establish a baseline for your conversion rates. We suggest 1) using our default template and 2) target customers who show high levels of engagement with your product for your first study.
>
> **Keep your calendar open** - Give your customers more options to book a time with you. Aim to keep your calendar availability high during your studies.
>
> **Archive Often** - kicking off a new study is super easy in Clockwork. We allow customers to edit live studies but it's often easier to archive stale studies and create a new one.