Working with Customers

You can use the TicketSource API to work with your customer data; retrieving, creating, updating and deleting customer records and the notes associated with them.

If you haven't already, you should go through our getting started guide for instructions on obtaining credentials and how to authenticate with the API.

Retrieving customer records

You can retrieve a list of all Customer resources on your TicketSource account by querying the /customers endpoint.

Sample Request:

$curl = curl_init('https://api.ticketsource.io/customers');
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
$customers = json_decode($response);

Sample Response:

{
    "data": [
        {
            "id": "cst-xxxxxxxxxx1",
            "type": "customer",
            "attributes": {
                "title": null,
                "first_name": "Sample",
                "last_name": "Customer",
                "address": {
                    "line_1": "Off Edge",
                    "line_2": "Station Approach",
                    "line_3": "Penarth",
                    "line_4": "United Kingdom",
                    "postcode": "CF64 3EE"
                },
                "telephone": "03336664466",
                "email": "support@ticketsource.co.uk",
                "membership": {
                    "identifier": null,
                    "start_date": null,
                    "end_date": null
                },
                "consent": {
                    "email": true,
                    "post": false,
                    "sms": false
                },
                "created_at": "2019-02-12T10:58:34+00:00",
                "updated_at": null
            },
            "links": {
                "self": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1",
                "bookings": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/bookings",
                "notes": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes"
            }
        },
        {
            ...
        }
    ],
    "links": {
        "first": "https://api.ticketsource.io/customers?page=1",
        "last": null,
        "prev": null,
        "next": "https://api.ticketsource.io/customers?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://api.ticketsource.io/customers",
        "per_page": 10,
        "to": 10
    }
}

You can also retrieve an individual Customer resource by appending the customer id to the endpoint used above:

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx1');

You can find out more about the properties of a Customer resource in our API reference.

Creating customer records

You can create a new Customer record by sending a JSON payload in a POST request to the /customers endpoint. An example of the JSON payload can be seen in the sample request below.

Sample Request:

$customerPayload = [
    'data' => [
        'type' => 'customer',
        'attributes' => [
            'title' => '',
            'first_name' => 'Karl',
            'last_name' => 'Jenkins',
            'address' => [
                'line_1' => '1 A Street',
                'line_2' => 'A Town',
                'line_3' => '',
                'line_4' => '',
                'postcode' => 'AB123CD',
            ],
            'email' => 'karl@karljenkins.com',
            'phone' => '01234555678',
            'membership' => [
                'identifier' => 'A12345BCD',
                'start_date' => '2020-01-01',
                'end_date' => '2021-12-31',
            ],
            'consent' => [
                'email' => true,
                'post' => false,
                'sms' => false,
            ],
        ],
    ],
];

$curl = curl_init('https://api.ticketsource.io/customers');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
]);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($customerPayload));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
$customer = json_decode($response);

Payload schema

Key	Notes
data	All API payloads are to be wrapped in a data key
data.type	For validation purposes all Customer related requests must have a type of customer
data.attributes	An object containing attributes used to create the Customer resource. See the table below for details.

data.attributes schema

Key

Notes

title

The customer's title

first_name

The customer's first name

last_name

The customer's last name

address

An object of attributes defining the customer's address:

line_1	The first line of the customer's address
line_2	The second line of the customer's address
line_3	The third line of the customer's address
line_4	The fourth line of the customer's address
postcode	The customer's address post code

The customer's email address

phone

The customer's phone number

membership

An object of attributes defining the customer's membership details:

identifier	The customer's membership identifier
start_date	The ISO 8601 date (YYYY-MM-DD) of the start of the customer's membership
end_date	The ISO 8601 date (YYYY-MM-DD) of the end of the customer's membership

consent

An object of attributes defining the customer's contact consent:

email	Whether the customer consents to contact via email
post	Whether the customer consents to contact via post
sms	Whether the customer consents to contact via sms

All attributes are optional when creating a customer record but at least one must be provided.

Sample Response:

Upon successful creation of a Customer record the API will return the record in it's response with a status code of 201 Created

{
    "data": {
        "id": "cst-xxxxxxxxxx2",
        "type": "customer",
        "attributes": {
            "title": null,
            "first_name": "Karl",
            "last_name": "Jenkins",
            "address": {
                "line_1": "1 A Street",
                "line_2": "A Town",
                "line_3": null,
                "line_4": null,
                "postcode": "AB123CD"
            },
            "telephone": "01234555678",
            "email": "karl@karljenkins.com",
            "membership": {
                "identifier": "A12345BCD",
                "start_date": "2020-01-01",
                "end_date": "2021-12-31"
            },
            "consent": {
                "email": true,
                "post": false,
                "sms": false
            },
            "created_at": "2020-04-09T16:36:05+00:00",
            "updated_at": null
        },
        "links": {
            "self": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx2",
            "bookings": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx2/bookings",
            "notes": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx2/notes"

        }
    }
}

Updating customer records

To update a Customer you can send a PATCH request to the Customer record's endpoint. The payload schema for updating is identical to the customer creation schema with the addition of a data.id value which must match the id used in the endpoint.

Sample Request:

$customerPayload = [
    'data' => [
        'type' => 'customer',
        'id' => 'cst-xxxxxxxxxx2',
        'attributes' => [
            'last_name' => 'Jenkin',
        ],
    ],
];

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx2');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
]);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($customerPayload));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
$customer = json_decode($response);

Only the attributes you want to update need to be provided. data.id must match the id in the endpoint.

Sample Response:

Upon successful updating a Customer record the API will return the record in it's response.

{
    "data": {
        "id": "cst-xxxxxxxxxx2",
        "type": "customer",
        "attributes": {
            "title": null,
            "first_name": "Karl",
            "last_name": "Jenkin",
            "address": {
                "line_1": "1 A Street",
                "line_2": "A Town",
                "line_3": null,
                "line_4": null,
                "postcode": "AB123CD"
            },
            "telephone": "01234555678",
            "email": "karl@karljenkins.com",
            "membership": {
                "identifier": "A12345BCD",
                "start_date": "2020-01-01",
                "end_date": "2021-12-31"
            },
            "consent": {
                "email": true,
                "post": false,
                "sms": false
            },
            "created_at": "2020-04-09T16:36:05+00:00",
            "updated_at": "2020-04-09T16:45:08+00:00"
        },
        "links": {
            "self": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx2",
            "bookings": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx2/bookings",
            "notes": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx2/notes"
        }
    }
}

Deleting customer records

To delete a Customer you can send a DELETE request to the Customer record's endpoint. No payload is required.

Sample Request:

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx2');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
]);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);

Sample Response:

Upon successful deletion of a customer record the API will respond with a blank response and a status code of 204 No Content

Customer Notes

As Customer Notes are directly related to their parent Customer resource, all of the endpoints below extend from the Customer resource endpoint, e.g. /customers/cst-xxxxxxxxxx1.

Retrieving customer note records
Creating customer note records
Deleting customer note records

Retrieving customer note records

You can retrieve a list of all Customer note resources for a given Customer resource by querying it's /customers/cst-xxxxxxxxxx1/notes endpoint.

Sample Request:

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes');
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
$response = curl_exec($curl);
$customers = json_decode($response);

Sample Response:

{
    "data": [
        {
            "id": "csn-xxxxxxxxxx1",
            "type": "customer-note",
            "attributes": {
                "description": "This is an example note for this customer",
                "created_by": "My Sample API App",
                "created_at": "2019-02-12T10:58:34+00:00",
                "updated_at": null
            },
            "links": {
                "self": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes/csn-xxxxxxxxxx1",
                "customer": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1"
            }
        },
        {
            ...
        }
    ],
    "links": {
        "first": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes?page=1",
        "last": null,
        "prev": null,
        "next": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes",
        "per_page": 10,
        "to": 10
    }
}

You can also retrieve an individual Customer Note resource by appending the customer note id to the endpoint used above:

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes/csn-xxxxxxxxxx1');

You can find out more about the properties of a Customer Note resource in our API reference.

Creating customer note records

You can create a new Customer Note record by sending a JSON payload in a POST request to the /customers/cst-xxxxxxxxxx1/notes/ endpoint. An example of the JSON payload can be seen in the sample request below.

Sample Request:

$customerPayload = [
    'data' => [
        'type' => 'customer_note',
        'attributes' => [
            'description' => 'This is a note about this customer',
            'created_by' => 'My TicketSource Integration',
        ],
    ],
];

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
]);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($customerPayload));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);
$customer = json_decode($response);

Payload schema

Key	Notes
data	All API payloads are to be wrapped in a data key
data.type	For validation purposes all Customer Note creation requests must have a type of customer_note
data.attributes	An object containing attributes used to create the Customer resource. See the table below for details.

data.attributes schema

Key	Notes
description	The contents of the note. required
created_by	Who or what this note was created by, this is a simple string and can be anything you like. required

Sample Response:

Upon successful creation of a Customer record the API will return the record in it's response with a status code of 201 Created

{
    "data": {
        "id": "csn-xxxxxxxxxx2",
        "type": "customer-note",
        "attributes": {
            "description": "This is a note about this customer",
            "created_by": "My TicketSource Integration",
        },
        "links": {
            "self": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes/csn-xxxxxxxxxx2",
            "customer": "https://api.ticketsource.io/customers/cst-xxxxxxxxxx1"
        }
    }
}

Deleting customer note records

To delete a Customer Note you can send a DELETE request to the Customer Note resource's endpoint. No payload is required.

Sample Request:

$curl = curl_init('https://api.ticketsource.io/customers/cst-xxxxxxxxxx1/notes/csn-xxxxxxxxxx2');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer '.'skl-xxxxxxxxxx'
]);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl);

Sample Response:

Upon successful deletion of a customer record the API will respond with a blank response and a status code of 204 No Content

Next steps

Learn to work with your booking data