people.md

title	People
nav_order	3

The primary key for a person is id. However the following fields are unique: email, phone_number, national_id_no and provider+uid. There are no specific requirements for input but a person needs to have either name, email, national id number or phone number.

It is possible to give a person ability to book on behalf of other people. This is linked through the parent_id attribute.

Attributes

Name	Type	Description
id	Integer	Automatically set
created_at	Datetime	Automatically set
updated_at	Datetime	Automatically set
name	String	Not required.
email	String	Not required.
phone_number	String	Not required. Phone number as stored. Also available as phonenumber (deprecated).
phone_number_formatted	String	Only returnable. E.164 formatted phone number with plus sign, international code, and no spaces or parentheses.
external_id	String	Not required
custom_data	Array	Not required. Key/value. Stored as strings.
date_of_birth	Date	Not required
national_id_no	String	Not required.
street	String	Not required.
city	String	Not required.
postal_code	String	Not required.
state	String	Not required.
country_code	String	Not required. ISO 3166-1 alpha-2.
notes	Text	Not required.
parent_id	Integer	Id of parent.
blocked	Boolean	Whether the person is blocked from booking.
locale	String	Person's preferred locale.
opt_in_marketing	Boolean	Only for output. Whether person has opted in to marketing.

Listing

GET /people will return all active people.

GET /people/all will return all people including those who are deactivated.

Response

[
  {
    "person": {
      "created_at": "2012-09-20T15:34:16+02:00",
      "custom_data": null,
      "date_of_birth": null,
      "email": "robot@booking.makeplans.com",
      "external_id": null,
      "id": 1,
      "name": "Espen Antonsen",
      "national_id_no": null,
      "notes": null,
      "phone_number": "",
      "phone_number_formatted": null,
      "date_of_birth": null,
      "street": null,
      "city": null,
      "postal_code": null,
      "state": null,
      "country_code": null,
      "parent_id": null,
      "updated_at": "2012-09-20T15:34:16+02:00"
    }
  }
]

Query Parameters

You can search multiple columns at once, for example email and phone_number, or you can use the shorthand search to search email, phone number, national id no or name.

Name	Type	Description
search	String
email	String
phone_number	String
external_id	String
name	String
date_of_birth	Date
national_id_no	String
since	DateTime	updated_at after param

Get person

GET /people/{person_id} will get a person with id {person_id}.

Add new person

POST /people will create a new person.

Update person

PUT /people/{person_id} will update existing person with id {person_id}.

Delete person

DELETE /people/{person_id} will delete existing person with id {person_id}.

Block person

PUT /people/{person_id}/block will block person with id {person_id} from making bookings.

Unblock person

PUT /people/{person_id}/unblock will unblock person with id {person_id}.

Authenticate person

POST /people/authenticate will authenticate a person. Specify credentials using person[email] or person[phone_number] and person[password].

Undelete person

PUT /people/{person_id}/undelete will undelete existing person with id {person_id}.

Merge person with another person

POST /people/{person_id}/merge?merge_person_id={merge_person_id} will merge existing person with id {person_id} and {merge_person_id}. All bookings for {merge_person_id} will be transferred to {person_id}. {merge_person_id} will be deleted. You can also specify attributes to update with {person} just like when creating/updating a person.

Person verification with a perishable token

The purpose of this feature is to verify a new or existing person in Makeplans on your website such as "login to see your bookings". The verification can be done either using email or SMS. When successful you will have verified either an email or a phone number. Thus you can either create a new person or retrieve an existing person knowing that the person has been verified.

Please note that this token is perishable, meaning that it will be removed from and unavailable for verification after 10 minutes.

Send perishable token

POST /people/perishable_token/send will send a SMS with a five digit code (the token) or an email with a link which includes the token in the URL. Specify either person[email] or person[phone_number].

Sending via email is not yet implemented. Only SMS token is possible.

Verify perishable token

POST /people/perishable_token/verify. This will return a person if authentication is successful. If the email or phone_number is already registered to a person then that person will be returned. If no person exists with the specified email/phone_number then a empty person object will be returned. You then have to make another call to create the person. If the token and the identifier do not match an error is returned.

Specify the token as perishable_token and the identifier in person[email] or person[phone_number].

List bookings for person

GET /people/{person_id}/bookings will retrieve all bookings for person with id {person_id}. You can also use other listings as described in the bookings listing such as GET /people/{person_id}/bookings/visible to include cancelled bookings.

List children for person

GET /people/{person_id}/children will retrieve all children for person with id {person_id}.