# The Clockwork API

## 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 %}