---
title: "Create a person"
method: POST
path: "/v1/locations/{locationId}/persons"
tags: ["Persons"]
---

# Create a person

`POST /v1/locations/{locationId}/persons`

## Request

- Base URL: `https://api.cliento.com`
- URL: `https://api.cliento.com/v1/locations/{locationId}/persons`
- Auth: HTTP bearer

Creates a person at the location. Send an `externalReference`, your own id for the person, to make the call safe to repeat. When a person at the location already has that reference, that person is returned unchanged with `200` and nothing is created. A person with an identity number that another person at the location already has, with the same `type`, is normally refused with `duplicate`.

## Path parameters

- `locationId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- PersonCreate
  - `address` Address
    - `city` string, nullable
    - `country` string, nullable: Free text; an ISO 3166-1 alpha-2 code is recommended.
    - `line1` string, nullable
    - `line2` string, nullable
    - `line3` string, nullable
    - `postCode` string, nullable
  - `communication` Communication: What the person has agreed to receive. In an update, a field you leave out keeps its value. For a new person `smsReminders`, `emailReminders` and `reviewReminders` start as true and `marketing` as false: send `marketing` as true only when the person has agreed to marketing.
    - `emailReminders` boolean: Booking reminders by email.
    - `marketing` boolean: Marketing messages.
    - `reviewReminders` boolean: Requests to review a visit.
    - `smsReminders` boolean: Booking reminders by SMS.
  - `dateOfBirth` string: ISO 8601 date.
  - `email` string
  - `externalReference` string: Your own id for it, at most 100 characters, such as its id in your system. It makes the create safe to repeat and lets you find it again. Compared exactly, letter case included.
  - `gender` 'male' | 'female' | 'other'
  - `identityNumber` IdentityNumber: A number issued by an authority that identifies a person, such as a personnummer. The accepted format of each type is listed under Persons.
    - `number` string, required: In the format of its type: twelve digits for a Swedish personnummer.
    - `type` string, required: The kind of number, in lower case, such as `se_personnummer` or `foreign`. More values may be added.
  - `name` string, required
  - `notes` string: Staff-facing notes, at most 1000 characters.
  - `onlineBookingBlocked` boolean: Set to true to stop the person booking online.
  - `otherPhoneNumber` string
  - `phoneNumber` string: Mobile number in E.164 format: a plus sign, the country code and the number, at most 15 digits.

## Response `200`

A person with this `externalReference` already existed.

- Person: Represents an individual a location serves. Belongs to one location.
  - `address` Address
    - `city` string, nullable
    - `country` string, nullable: Free text; an ISO 3166-1 alpha-2 code is recommended.
    - `line1` string, nullable
    - `line2` string, nullable
    - `line3` string, nullable
    - `postCode` string, nullable
  - `communication` Communication, required: What the person has agreed to receive. In an update, a field you leave out keeps its value. For a new person `smsReminders`, `emailReminders` and `reviewReminders` start as true and `marketing` as false: send `marketing` as true only when the person has agreed to marketing.
    - `emailReminders` boolean: Booking reminders by email.
    - `marketing` boolean: Marketing messages.
    - `reviewReminders` boolean: Requests to review a visit.
    - `smsReminders` boolean: Booking reminders by SMS.
  - `createdAt` string, date-time
  - `dateOfBirth` string: ISO 8601 date.
  - `email` string
  - `externalReference` string: Your own id for it, as sent when it was created.
  - `gender` string: One lower-case word such as `female`. More values may be added.
  - `id` string, required
  - `identityNumber` IdentityNumber: A number issued by an authority that identifies a person, such as a personnummer. The accepted format of each type is listed under Persons.
    - `number` string, required: In the format of its type: twelve digits for a Swedish personnummer.
    - `type` string, required: The kind of number, in lower case, such as `se_personnummer` or `foreign`. More values may be added.
  - `locationId` string, required
  - `name` string
  - `notes` string: Staff-facing notes, at most 1000 characters.
  - `onlineBookingBlocked` boolean, required: True when the person may not book online.
  - `otherPhoneNumber` string
  - `owner` CustomerOwner, required: Whose customer a person is within its location: the location's own, or that of one of the location's resources. A salon that rents out chairs uses it: a person served by a hairdresser who rents a chair is that resource's customer, and a person served by an employee is the location's. Many locations never record it, so `unassigned` is common and says nothing either way.
    - `resourceId` string: The resource (see Resources) whose customer the person is. Present when `type` is `resource`.
    - `type` 'location' | 'resource' | 'unassigned', required: `location`: the location's own customer. `resource`: the customer of one resource, named by `resourceId`. `unassigned`: not recorded. More values may be added.
  - `phoneNumber` string: Mobile number, in E.164 format when it was set through this API.
  - `updatedAt` string, date-time

## Other responses

- `201`: The person was created.
- `default`: Any failure. See the Errors section.

---

[API](https://skmtc.dev/cliento/apis/cliento-api.md) · [All operations](https://skmtc.dev/cliento/apis/cliento-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cliento/apis/cliento-api/revisions/29ca811bc061?raw)