Customers API Documentation

Overview

This collection contains customer accounts associated with the requesting user's organization.

Sub-collections

Each customer record has multiple sub-collections containing records pertinent to that customer, such as documents and emergency contacts.

Fields

Name Type Restrictions Required? Description
id integer Automatic Automatic The unique identifier of the customer. This is placed in the URL when making API calls for the customer.
url string Automatic Automatic The unique API URL of the customer.
email string (email address) Must be a valid email address. Yes The customer's email address. This is used to log in and for notifications.
first_name string Must not be blank. Yes The customer's first name.
last_name string Must not be blank. Yes The customer's last name.
preferred_name string At most 180 characters in length. No The customer's preferred name.
birthday string (ISO-8601 date) Must be an ISO-8601 date string. Yes The customer's birthday.
address_postcode string None No The postcode or zip code of the customer's address.
address_street_1 string None No The customer's street address line 1.
address_street_2 string None No The customer's street address line 2.
address_city string None No The city of the customer's address.
address_state string None No If US state, use two-letter state abbreviation (see: https://pe.usps.com/text/pub28/28apb.htm), else full state/province name
address_country string None No Two-letter country code (see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
government_id string None No The customer's government ID number.
telephone string None No The customer's telephone number.
gender string Must be one of the supported gender options, or null. No The customer's gender.
pronouns string None No The customer's pronouns.
has_opted_in_to_marketing boolean None No Whether the customer has opted into marketing communications.
barcode string At most 128 characters in length. No The customer's barcode, used for the Check-In and Check-Out Sites.
profile_image url (read), image file (write) Must be a JPEG or PNG image (or null) if writing. Will be a URL or null when reading. No The customer's profile image. When written, the server will convert the image to a 512 by 512 pixel JPEG image (detail), and save it with a random filename. When read, the server will return a link to the image file.
profile_image_small url Automatic Automatic A link to the small 128 by 128 version of the customer's profile image. This is generated automatically when the full-size image is added to the customer.
home_location_id integer Must be the ID of a location in your organization. No The ID of the customer's home location. This is used to attribute revenue for online purchases which do not have a specific location, such as multi-location entry passes.
home_location_url string (URL) Automatic Automatic The API URL of the customer's home location.
home_location_name string Automatic Automatic The name of the customer's home location.
capitan_invite_sent boolean Automatic Automatic Whether an email has been sent to the customer inviting them to set up a Capitan Climber App account.
has_capitan_login boolean Automatic Automatic Whether the customer has created a password to log into the Capitan Climber App.
check_in_count integer Automatic Automatic The number of times the customer has checked in.
has_active_membership boolean Automatic Automatic Whether the customer has an active membership. They must be a member of the membership; if they own a membership which is assigned to someone else, it is not counted.
has_active_youth_programming_membership boolean Automatic Automatic Whether the customer has a youth programming membership (a membership whose membership type has is_youth_programming set to true).
has_active_non_youth_programming_membership boolean Automatic Automatic Whether the customer has a non-youth programming membership (a membership whose membership type has is_youth_programming set to false).
has_membership_with_future_start boolean Automatic Automatic Whether the customer has a membership with a future start date.
has_frozen_membership boolean Automatic Automatic Whether the customer has a frozen membership.
number_of_available_entry_passes integer Automatic Automatic The number of entry pass usages that the customer has available.
active_waiver_exists boolean Automatic Automatic Whether the customer has an active waiver document.
latest_waiver_expiration_date string (ISO-8601 date) Automatic Automatic The date when the customer's active waiver document will expire. If the customer has multiple active waivers, this gives the latest expiration date. If the customer has a waiver which does not expire, or has no active waiver, this field will be null.
active_proficiency_names list of strings Automatic Automatic The names of the active proficiencies assigned to this customer.
tags list of strings Automatic Automatic The tags assigned to this customer.
custom_field_values list of JSON objects Automatic Automatic A list of objects containing this customer's value for each of your org's configured custom customer fields. See the custom field values table for the object specification.
has_medical_notes boolean Automatic Automatic Whether this customer has at least one medical note.
first_check_in_timestamp string (ISO-8601 datetime) Automatic Automatic When this customer first checked into a location. Will be null if they have no check-ins.
latest_check_in_timestamp string (ISO-8601 datetime) Automatic Automatic When this customer most recently checked into a location. Will be null if they have no check-ins.
first_membership_timestamp string (ISO-8601 datetime) Automatic Automatic When this customer first became a member. Will be null if they have never had a membership.
created_at string (ISO-8601 datetime) Automatic Automatic When the customer was added to the Capitan database.
updated_at string (ISO-8601 datetime) Automatic Automatic When the customer's record in the Capitan database was last updated.
event_vouchers_url string (URL) Automatic Automatic The API URL of this customer's event vouchers subcollection.
credits_url string (URL) Automatic Automatic The API URL of this customer's credits subcollection.
emergency_contacts_url string (URL) Automatic Automatic The API URL of this customer's emergency contacts subcollection.
medical_notes_url string (URL) Automatic Automatic The API URL of this customer's medical notes subcollection.
notes_url string (URL) Automatic Automatic The API URL of this customer's notes subcollection.
alerts_url string (URL) Automatic Automatic The API URL of this customer's alerts subcollection.
documents_url string (URL) Automatic Automatic The API URL of this customer's documents subcollection.
relations_url string (URL) Automatic Automatic The API URL of this customer's relations subcollection.
check_ins_url string (URL) Automatic Automatic The API URL of this customer's check-ins subcollection.
guest_pass_usages string (URL) Automatic Automatic The API URL of this customer's guest pass usages subcollection.
shared_passes_url string (URL) Automatic Automatic The API URL of this customer's shared passes subcollection.
memberships_url string (URL) Automatic Automatic The API URL of this customer's memberships subcollection.
entry_passes_url string (URL) Automatic Automatic The API URL of this customer's entry passes subcollection.
challenges_url string (URL) Automatic Automatic The API URL of this customer's challenges subcollection.
payments_url string (URL) Automatic Automatic The API URL of this customer's payments subcollection.
proficiencies_url string (URL) Automatic Automatic The API URL of this customer's proficiencies subcollection.
reservations_url string (URL) Automatic Automatic The API URL of this customer's reservations subcollection.
reservation_parts_url string (URL) Automatic Automatic The API URL of this customer's reservation parts subcollection.
pending_relations_url string (URL) Automatic Automatic The API URL of this customer's requested pending relations subcollection.
incoming_pending_relations_url string (URL) Automatic Automatic The API URL of this customer's incoming pending relations subcollection.
activity_log_url string (URL) Automatic Automatic The API URL of this customer's activity log.

Gender Options

Name Syntax
Male M
Female F
Non-binary N
Prefer not to say P

Custom Field Values Object

Each custom fields value is a JSON object with the following fields:

Name Type Editable? Description
field_id integer No The ID of the custom field. Not editable.
field_name string No The name of the custom field. Not editable.
value string Yes The customer's value for this custom field.

Filters

See the filtering documentation for more information on how to use filters in the Capitan API.

Name Syntax Description
General Search search Filters for customers containing the given search terms. Matches against a number of fields, including email, first name, last name, telephone, and barcode.
Minimum Age age_min Filters for customers at or older than the given age.
Maximum Age age_max Filters for customers at or younger than the given age.
Minimum Birthday birthday_min Filters for customers with a birthday on or later than the given date.
Maximum Birthday birthday_max Filters for customers with a birthday on or earlier than the given date.
Minimum Account Created Date created_at_min Filters for customers whose accounts were created on or after the given date (in the local time of your org).
Maximum Account Created Date created_at_max Filters for customers whose accounts were created on or before the given date (in the local time of your org).
Postcode / ZIP Code address_postcode Filters for customers whose postcode / zip code is equal to the provided value. The match is case-insensitive. Multiple codes may be provided, separated by commas, in which case customers matching any of the given codes will be returned.
Gender gender Filters for customers with the given gender.
Marketing Opt-In Status has_opted_in_to_marketing Filters for customers who have ("true") or have not ("false") opted into marketing communications.
Minimum Check-In Count check_in_count_min Filters for customers who have checked in at least the given number of times.
Maximum Check-In Count check_in_count_max Filters for customers who have checked in at most the given number of times.
Minimum First Membership Date first_membership_timestamp_min Filters for customers who first became a member on or after the given date (in the local time of your org). Only returns current and former members.
Maximum First Membership Date first_membership_timestamp_max Filters for customers who first became a member on or before the given date (in the local time of your org). Only returns current and former members.
Active Membership Status has_active_membership Filters for customers who have ("true") or do not have ("false") an active membership.
Active Youth Programming Membership Status has_active_youth_programming_membership Filters for customers who have ("true") or do not have ("false") an active youth programming membership.
Active Non-Youth Programming Membership Status has_active_non_youth_programming_membership Filters for customers who have ("true") or do not have ("false") an active non-youth programming membership.
Membership Status (Future Start Date) has_membership_with_future_start Filters for customers who have ("true") or do not have ("false") a membership with a future start date.
Frozen Membership Status has_frozen_membership Filters for customers who have ("true") or do not have ("false") a frozen membership.
Active Membership Name has_active_membership Filters for customers who have an active membership with the given name. Uses case-insensitive substring matching. For example, "month" would match a membership named "Monthly".
Tags tags Filters for customers with the given comma-separated tags. If multiple tags are provided, a customer must have all of them in order to be returned.
Has Reservation For Event Type has_event_type_reservation Filters for customers who have a reservation for the given event type ID.
Minimum Latest Check-In Date latest_check_in_timestamp_min Filters for customers whose latest check-in was on or after the given date (in the local time of your org).
Maximum Latest Check-In Date latest_check_in_timestamp_max Filters for customers whose latest check-in was on or before the given date (in the local time of your org).
Proficiencies has_proficiencies Filters for customers with the given comma-separated proficiency IDs. If multiple proficiency IDs are provided, a customer must have all of them in order to be returned.
Association Memberships has_association_memberships Filters for customers who are members of the given comma-separated list of association IDs. If multiple association IDs are provided, a customer must belong to all of them in order to be returned.
Challenge has_challenge Filters for customers who have the given challenge ID. The challenge may be in progress or completed for the customer.

Operations

List

Request
GET /api/customers/

Response
200 OK
{
    "count": 17,
    "next": "https://api.hellocapitan.com/api/customers/?page=2",
    "previous": null,
    "results": [
        {
            "id": 35,
            "url": "https://api.hellocapitan.com/api/customers/35/",
            "email": "joe@example.com",
            "first_name": "Joe",
            ...
        },
        ...
    ]
}

Read

Request
GET /api/customers/35/

Response
200 OK
{
    "id": 35,
    "url": "https://api.hellocapitan.com/api/customers/35/",
    "email": "joe@example.com",
    "first_name": "Joe",
    ...
}

Replace

Request
PUT /api/customers/53/
{
    "email": "dave@example.com",
    "first_name": "Dave",
    "last_name": "Johnson",
    "birthday": "1985-04-13"
}

Response
200 OK
{
    "id": 53,
    "url": "https://api.hellocapitan.com/api/customers/53/",
    "first_name": "Dave",
    ...
}

Update

Request
PATCH /api/customers/53/
{
    "first_name": "David"
}

Response
200 OK
{
    "id": 53,
    "url": "https://api.hellocapitan.com/api/customers/53/",
    "first_name": "David",
    ...
}

Write Profile Image

Note: the image will be automatically cropped to a square (if it isn't already square, we will crop to the largest square possible, centered), resampled to 512 by 512 pixels (using Lanczos sampling) and saved as a JPEG image with a random filename. If a PNG image with an alpha channel is provided, the alpha channel will be removed.

Request
PATCH /api/customers/53/
Content-Disposition: form-data; name="profile_image"; filename="customer_photo.jpg"
Content-Type: image/jpeg
(image data)

Response
200 OK
{
    "id": 53,
    "url": "https://api.hellocapitan.com/api/customers/35/",
    "email": "joe@example.com",
    "first_name": "Joe",
    ...
}