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.

Customers

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

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

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

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

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

Menu