Working with Customers

You can use the TicketSource API to retrieve, create, update and delete your customer data. This guide will go through the necessary call to perform these tasks can be used for mail merges or syncing with external CRM systems.

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.

Contents of this page

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"
            }
        },
        {
            ...
        }
    ],
    "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');

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 Custom 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
email 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

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"
        }
    }
}

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);

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"
        }
    }
}

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

Menu