Customers

This endpoint is used for managing customer data

Get customers

get

https://api.collinsbookings.com/apihttps://api-playpen.collinsbookings.com/api

/customers

Returns an array of all customers which the authenticated user is authorised to view. The response will be paginated.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

associated_venuesstring[]Optional

Filters on associated venue IDs. If a comma-separated list is passed, customers associated with any of the given venue IDs will be returned.

Example: ["5c80155a86bb06bc1401ea1e","5c8015884e68d55f12c7ec9d"]

booking_datestring · dateOptional

Filters on customers who had a booking booked within the specified dates.

Example: 2019-03-10

booking_date_fromstring · dateOptional

Filters on customers who had a booking booked on or later than the given date.

Example: 2017-01-05

booking_date_tostring · dateOptional

Filters on customers who had a booking booked on or before the given date.

Example: 2018-01-05

created_datestring · dateOptional

Filters on customers who were created on the given date.

Example: 2019-01-01

created_date_fromstring · dateOptional

Filters on customers who were created on or after the given date.

Example: 2019-01-01

created_date_tostring · dateOptional

Filters on customers who were created on or before the given date.

Example: 2019-02-01

dob_monthintegerOptional

Filter on month of birth. If a comma-separated list is passed, customers with any of the specified birth months will be returned

Example: {"summary":"Filters by customers born in January","value":[1]}

emailstring · email[]Optional

Filter on a customer's email address

Example: [email protected]

full_namestringOptional

Filter on a full name

Example: John Doe

labelsstring[]Optional

Filter on labels attached to a customer. If a comma-separated list is passed, customers with any of the given labels will be returned.

Example: ["VIP","Regular Customer"]

last_updatedstring · dateOptional

Filter on the date the customer was last updated

Example: 2019-03-10

last_updated_fromstring · dateOptional

Filter on customers who were last updated on or after the given date.

Example: 2019-01-01

last_updated_tostring · dateOptional

Filter on customers who were last updated on or before the given date.

Example: 2019-02-01

opted_instring[]Optional

Filter by customers who have opted into the specified preference ID. If a comma-separated list is passed, customers opted into any of the given preference IDs will be returned.

Example: 5c8015f15dbf3bec42c4c66f

opted_in_datestring · dateOptional

Filter by customers who opted into the specified preference ID on the given date. Must be used in conjunction with the opted_in parameter.

Example: 2017-01-05

opted_in_date_fromstring · dateOptional

Filter by customers who opted into the specified preference ID on or after the given date. Must be used in conjunction with the opted_in parameter.

Example: 2017-01-05

opted_in_date_tostring · dateOptional

Filter by customers who opted into the specified preference ID on or before the given date. Must be used in conjunction with the opted_in parameter.

Example: 2017-01-14

opted_outstring[]Optional

Filter by customers who have opted out of the specified preference ID. If a comma-separated list is passed, customers who have opted out any of the given preference IDs will be returned.

Example: 5c8015f15dbf3bec42c4c66f

opted_out_datestring · dateOptional

Filter by customers who opted out of the specified preference ID on the given date. Must be used in conjunction with the opted_out parameter.

Example: 2017-01-05

opted_out_date_fromstring · dateOptional

Filter by customers who opted out of the specified preference ID on or after the given date. Must be used in conjunction with the opted_out parameter.

Example: 2017-01-05

opted_out_date_tostring · dateOptional

Filter by customers who opted out of the specified preference ID on or before the given date. Must be used in conjunction with the opted_out parameter.

Example: 2017-01-14

querystringOptional

Filter by customers which have a full_name, email, company or phone similar to the search query.

Example: @example.com

limitinteger · min: 1 · max: 30Optional

Limit the response to the specified number of records.

Default: 30Example: 30

sortstring[]Optional

The fields which the results should be sorted by. If this value is not specified, the records will be sorted in order of relevance to the query parameter. If the query parameter is not specified, records will be sorted in order of their created_date. To sort in decending order, prefix the field name with a '-' character.

Example: -last_updated

pagestringOptional

The page number to retrieve results for. Learn more about pagination

Default: 1Example: 2

Responses

200

Customers were successfully retrieved

application/json

401

Authorization credentials were required but not found

application/json

403

The request cannot be carried out using the given credentials

404

The requested resource could not be found

application/json

429

The number of requests remaining in the current rate limit window has been exceeded

application/json

get

/customers

HTTPcURLJavaScriptPython

GET /api/customers HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "customers": [
    {
      "id": "5314491e0a8efb6d7c19c39c",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "[phone]",
      "company": "The Access Group",
      "company_address": {
        "street": "Penn Street",
        "city": "London",
        "post_code": "N1 5DL"
      },
      "dob": "1995-01-13",
      "custom_field_value": "12345",
      "associated_venues": [
        "5c80155a86bb06bc1401ea1e",
        "5c8015884e68d55f12c7ec9d"
      ],
      "marketing_preferences": [
        {
          "id": "5c8015f15dbf3bec42c4c66f",
          "opt_in_date": "2017-01-05 00:00:00",
          "opt_out_date": "2017-01-14 00:00:00",
          "opted_in": true
        }
      ],
      "bookings": [
        {
          "id": "5c8015d346acc0fb47f1d900",
          "date": "2019-01-01 00:00:00",
          "venue_id": "5c8015e1739381c2e6caac2f"
        }
      ],
      "labels": [
        "VIP",
        "Regular Customer"
      ],
      "notes": "This guy loves our house white wine",
      "created_date": "2019-03-06 17:00:00",
      "last_updated": "2019-03-08 17:00:00"
    }
  ]
}

Create a customer

post

https://api.collinsbookings.com/apihttps://api-playpen.collinsbookings.com/api

/customers

Creates a new customer

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

emailstring · email · max: 255Optional

The customer's email address

Example: [email protected]

first_namestring · max: 255Optional

The customer's first name

Example: John

last_namestring · max: 255Optional

The customer's last name

Example: Doe

phonestring · max: 20Optional

The customer's phone number

Example: [phone]

companystring · max: 255Optional

The name of the customer's company

Example: The Access Group

dobstring · dateOptional

The customer's date of birth in the YYYY-MM-DD format

Example: 1995-01-13

custom_field_valueany · max: 255Optional

The value given for the custom field

Example: 12345

associated_venuesstring[]Optional

An array of venue IDs this customer should be associated with

Example: ["5c80155a86bb06bc1401ea1e","5c8015884e68d55f12c7ec9d"]

marketing_preference_idsstring[]Optional

An array of marketing preference IDs which the user should be opted in to.

Example: ["5c80155a86bb06bc1401ea1e","5c8015884e68d55f12c7ec9d"]

marketing_preferencesobjectOptional

An object of marketing preference IDs as the key, and whether or not the user should be opted in or out of as the value.

Example: {"5c80155a86bb06bc1401ea1e":true,"5c8015884e68d55f12c7ec9d":false}

labelsstring[]Optional

An array of labels which should be set on the customer

Example: ["VIP","Regular Customer"]

notesstring · max: 1000Optional

Any additional notes to make about the customer

Example: This guy loves our house white wine

Responses

201

Successfully added a customer

application/json

401

Authorization credentials were required but not found

application/json

403

The request cannot be carried out using the given credentials

404

The requested resource could not be found

application/json

422

The request could not be processed because it did not pass validation

429

The number of requests remaining in the current rate limit window has been exceeded

application/json

post

/customers

HTTPcURLJavaScriptPython

POST /api/customers HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 582

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "[phone]",
  "company": "The Access Group",
  "company_address": {
    "street": "23 Penn Street",
    "city": "London",
    "post_code": "N1 5DL"
  },
  "dob": "1995-01-13",
  "custom_field_value": "12345",
  "associated_venues": [
    "5c80155a86bb06bc1401ea1e",
    "5c8015884e68d55f12c7ec9d"
  ],
  "marketing_preference_ids": [
    "5c80155a86bb06bc1401ea1e",
    "5c8015884e68d55f12c7ec9d"
  ],
  "marketing_preferences": {
    "5c80155a86bb06bc1401ea1e": true,
    "5c8015884e68d55f12c7ec9d": false
  },
  "labels": [
    "VIP",
    "Regular Customer"
  ],
  "notes": "This guy loves our house white wine"
}

{
  "customer": {
    "id": "5314491e0a8efb6d7c19c39c",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "[phone]",
    "company": "The Access Group",
    "company_address": {
      "street": "Penn Street",
      "city": "London",
      "post_code": "N1 5DL"
    },
    "dob": "1995-01-13",
    "custom_field_value": "12345",
    "associated_venues": [
      "5c80155a86bb06bc1401ea1e",
      "5c8015884e68d55f12c7ec9d"
    ],
    "marketing_preferences": [
      {
        "id": "5c8015f15dbf3bec42c4c66f",
        "opt_in_date": "2017-01-05 00:00:00",
        "opt_out_date": "2017-01-14 00:00:00",
        "opted_in": true
      }
    ],
    "bookings": [
      {
        "id": "5c8015d346acc0fb47f1d900",
        "date": "2019-01-01 00:00:00",
        "venue_id": "5c8015e1739381c2e6caac2f"
      }
    ],
    "labels": [
      "VIP",
      "Regular Customer"
    ],
    "notes": "This guy loves our house white wine",
    "created_date": "2019-03-06 17:00:00",
    "last_updated": "2019-03-08 17:00:00"
  }
}

Get a customer

get

https://api.collinsbookings.com/apihttps://api-playpen.collinsbookings.com/api

/customers/{customerId}

Returns details about a specific customer

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

customerIdstringRequired

The ID of the customer you want to retreive

Responses

200

The customer was successfully retrieved

application/json

401

Authorization credentials were required but not found

application/json

403

The request cannot be carried out using the given credentials

404

The requested resource could not be found

application/json

429

The number of requests remaining in the current rate limit window has been exceeded

application/json

get

/customers/{customerId}

HTTPcURLJavaScriptPython

GET /api/customers/{customerId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "customer": {
    "id": "5314491e0a8efb6d7c19c39c",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "[phone]",
    "company": "The Access Group",
    "company_address": {
      "street": "Penn Street",
      "city": "London",
      "post_code": "N1 5DL"
    },
    "dob": "1995-01-13",
    "custom_field_value": "12345",
    "associated_venues": [
      "5c80155a86bb06bc1401ea1e",
      "5c8015884e68d55f12c7ec9d"
    ],
    "marketing_preferences": [
      {
        "id": "5c8015f15dbf3bec42c4c66f",
        "opt_in_date": "2017-01-05 00:00:00",
        "opt_out_date": "2017-01-14 00:00:00",
        "opted_in": true
      }
    ],
    "bookings": [
      {
        "id": "5c8015d346acc0fb47f1d900",
        "date": "2019-01-01 00:00:00",
        "venue_id": "5c8015e1739381c2e6caac2f"
      }
    ],
    "labels": [
      "VIP",
      "Regular Customer"
    ],
    "notes": "This guy loves our house white wine",
    "created_date": "2019-03-06 17:00:00",
    "last_updated": "2019-03-08 17:00:00"
  }
}

Update a customer

put

https://api.collinsbookings.com/apihttps://api-playpen.collinsbookings.com/api

/customers/{customerId}

Updates an existing customer

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

customerIdstringRequired

The ID of the customer you want to update

Body

application/json

idstringOptional

The customer's ID

Example: 5314491e0a8efb6d7c19c39c

emailstring · emailOptional

The customer's email address

Example: [email protected]

first_namestringOptional

The customer's first name

Example: John

last_namestringOptional

The customer's last name

Example: Doe

phonestringOptional

The customer's phone number

Example: [phone]

companystringOptional

The name of the customer's company

Example: The Access Group

dobstringOptional

The customer's date of birth

Example: 1995-01-13

custom_field_valuestringOptional

The value given for the custom field

Example: 12345

associated_venuesstring[]Optional

An array of associated venue IDs

Example: ["5c80155a86bb06bc1401ea1e","5c8015884e68d55f12c7ec9d"]

labelsstring[]Optional

An array of labels that have been applied to the customer

Example: ["VIP","Regular Customer"]

notesstringOptional

Any notes that have been applied to the customer

Example: This guy loves our house white wine

created_datestring · date-time · nullableOptional

The date and time the customer was created.

Prior to February 2019, we did not keep a record of the created date, except for some situations such as data imports. If we don't have the created date for a customer, null will be returned instead.

Example: 2019-03-06 17:00:00

last_updatedstring · date-timeOptional

The date and time the customer was last updated

Example: 2019-03-08 17:00:00

Responses

200

The customer was successfully updated

application/json

401

Authorization credentials were required but not found

application/json

403

The request cannot be carried out using the given credentials

404

The requested resource could not be found

application/json

422

The request could not be processed because it did not pass validation

429

The number of requests remaining in the current rate limit window has been exceeded

application/json

put

/customers/{customerId}

HTTPcURLJavaScriptPython

PUT /api/customers/{customerId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 774

{
  "id": "5314491e0a8efb6d7c19c39c",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "[phone]",
  "company": "The Access Group",
  "company_address": {
    "street": "Penn Street",
    "city": "London",
    "post_code": "N1 5DL"
  },
  "dob": "1995-01-13",
  "custom_field_value": "12345",
  "associated_venues": [
    "5c80155a86bb06bc1401ea1e",
    "5c8015884e68d55f12c7ec9d"
  ],
  "marketing_preferences": [
    {
      "id": "5c8015f15dbf3bec42c4c66f",
      "opt_in_date": "2017-01-05 00:00:00",
      "opt_out_date": "2017-01-14 00:00:00",
      "opted_in": true
    }
  ],
  "bookings": [
    {
      "id": "5c8015d346acc0fb47f1d900",
      "date": "2019-01-01 00:00:00",
      "venue_id": "5c8015e1739381c2e6caac2f"
    }
  ],
  "labels": [
    "VIP",
    "Regular Customer"
  ],
  "notes": "This guy loves our house white wine",
  "created_date": "2019-03-06 17:00:00",
  "last_updated": "2019-03-08 17:00:00"
}

{
  "customer": {
    "id": "5314491e0a8efb6d7c19c39c",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "[phone]",
    "company": "The Access Group",
    "company_address": {
      "street": "Penn Street",
      "city": "London",
      "post_code": "N1 5DL"
    },
    "dob": "1995-01-13",
    "custom_field_value": "12345",
    "associated_venues": [
      "5c80155a86bb06bc1401ea1e",
      "5c8015884e68d55f12c7ec9d"
    ],
    "marketing_preferences": [
      {
        "id": "5c8015f15dbf3bec42c4c66f",
        "opt_in_date": "2017-01-05 00:00:00",
        "opt_out_date": "2017-01-14 00:00:00",
        "opted_in": true
      }
    ],
    "bookings": [
      {
        "id": "5c8015d346acc0fb47f1d900",
        "date": "2019-01-01 00:00:00",
        "venue_id": "5c8015e1739381c2e6caac2f"
      }
    ],
    "labels": [
      "VIP",
      "Regular Customer"
    ],
    "notes": "This guy loves our house white wine",
    "created_date": "2019-03-06 17:00:00",
    "last_updated": "2019-03-08 17:00:00"
  }
}

Delete a customer

delete

https://api.collinsbookings.com/apihttps://api-playpen.collinsbookings.com/api

/customers/{customerId}

Deletes an existing customer

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

customerIdstringRequired

The ID of the customer you want to delete

Responses

204

The customer was successfully deleted

404

The requested resource could not be found

application/json

429

The number of requests remaining in the current rate limit window has been exceeded

application/json

delete

/customers/{customerId}

HTTPcURLJavaScriptPython

DELETE /api/customers/{customerId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content