Webhooks API Documentation BETA

Get Started

Follow these simple steps to register your app and get started with the Pike13 Webhooks API. Only OAuth2 tokens registered to those with the role of owner or higher can access the Webhooks API.

API Description

The purpose of the Webhooks API is to automatically notify you and your services of changes within your business. Remember, only staff members with the role of owner or higher have access to the API. For example, when a new client signs up for your business, we'll automatically send you a JSON payload.

Interaction with the Webhooks API is two parts: subscribing to topics and receiving notifications.

Subscribing

Subscribe using the REST API endpoint. Note that it conforms to JSON API version 1.0. Choose what kinds of notifications should be sent based on available topics.

Receiving

Receive notifications through POST requests. The payload is automatically POSTed to the target server when a change corresponding to a webhook happens.

Example Flow

Once you have an OAuth2 token for an owner of your business, you can subscribe to an available topic.

Let's create a webhook that triggers whenever a new person is created in your business:


SUBSCRIPTION REQUEST

curl -X POST https://mybiz.pike13.com/api/v3/webhooks \
-H 'Authorization: Bearer XXXXXX' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
  "data": {
    "type": "webhooks",
      "attributes": {
        "target": "https://target.example.com",
        "topic": "person.created"
        }
      }
    }'

The target attribute specifies the endpoint to which we will send a notification.


SUBSCRIPTION RESPONSE

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1",
    "type": "webhooks",
    "links": {
      "self": "https://subdomain.pike13.com/api/v3/webhooks/1"
    },
    "attributes": {
      "account_id": 1,
      "business_id": 1,
      "topic": "person.created",
      "target": "https://target.example.com/",
      "name": null,
      "description": null
    }
  }
}

After this successful subscription, if a person is created for the business, a server on https://target.example.com/ will receive a message like this:


NOTIFICATION PAYLOAD

POST https://target.example.com/
Content-Type: application/json

{
  "topic": "person.created",
  "webhook_id": 1,
  "business_id": 1,
  "data": {
    "people": [
      {
        "id": 10,
        "address": null,
        "birthdate": null,
        "business_id": 1,
        "deleted_at": null,
        "dependents": [

        ],
        "email": null,
        "pronoun": null,
        "first_name": "John",
        "guardian_email": null,
        "guardian_name": "Nathan Doe",
        "hidden_at": null,
        "is_member": false,
        "joined_at": "2019-02-19T23:24:02Z",
        "last_name": "Doe",
        "location": {
          "id": 30742,
          "name": "Example Business",
          "slug": "example-business"
        },
        "middle_name": null,
        "name": "John Doe",
        "phone": "123 456 7890",
        "primary_staff_member": {
          "id": 2,
          "name": "Joseph Cremin"
        },
        "providers": [

        ],
        "secondary_info_field": "No Membership",
        "timezone": "America/Los_Angeles",
        "updated_at": "2019-02-19T23:24:02Z"
      }
    ]
  }
}

Once you have received this payload, you must respond with a 200 status code within 10 seconds, or else it is considered an error on our end.

The data field shows the most up to date status of the resource, in this case a person. It is not identical to the json returned by the person desk endpoint If you require more fields about a person, access the corresponding Core API endpoint upon receiving a webhook: /api/v2/desk/people/:id

Event occurrence

Core API resource payload url:

Desk

GET /api/v2/desk/event_occurrences/:id

See the core api doc

Resource Attributes

data.event_occurrences[0]

integer

Event occurrence's ID.

event_id

integer

Event's ID.

name

string

Event's name.

description

string

Event's description.

duration_in_minutes

string

Event occurrence's length of duration in minutes.

service_id

integer

Service's ID.

service_type

string

Service's Type. One of [GroupClass, Appointment, Course].

service_name

string

Service's Name.

location_id

integer

Location's ID.

room_id

integer

Event's Room ID.

room_name

string

Event's Room Name.

start_at

timestamp

Timestamp for when the event occurrence starts.

end_at

timestamp

Timestamp for when the event occurrence ends.

created_at

timestamp

Timestamp for when the event occurrence was created.

updated_at

timestamp

Timestamp for when the event occurrence was last updated.

updating

boolean

Boolean value of whether event is in the process of updating its underlying iCal object.

timezone

string

Event occurrence's timezone.

attendance_complete

boolean

Boolean value of whether event occurrence has had its attendance confirmed.

visits_count

integer

Integer value of the total amount of clients enrolled.

state

string

Event occurrence's state. One of [active, canceled, deleted, reserved].

full

boolean

Boolean value of whether event occurrence is at max capacity.

visitors_can_view

boolean

Boolean value of whether visitors (without an account) can see the event.

clients_can_view

boolean

Boolean value of whether clients can see the event.

members_can_view

boolean

Boolean value of whether members can see the event.

clients_can_book

boolean

Boolean value of whether clients can enroll online for the event.

members_can_book

boolean

Boolean value of whether members can enroll online for the event.

capacity_remaining

integer

Event occurrence's remaining capacity.

anonymous_staff

boolean

Boolean value of whether the names of instructors are shown in the event.

staff_members

array

Array of people objects who are instructing this event occurrence. Empty if no instructor is currently assigned.

id	integer	Staff member's ID.
name	string	Staff member's name.

people

array

Array of people objects who are attending this event occurrence. Empty if no person is currently enrolled.

id	integer	Person's ID.
name	string	Person's name.

event_occurrence.upcoming

Triggers services.reminder_period_in_hours + 1 hours before event starts. If reminder_period_in_hours is not set, then this triggers 24 hours before event starts.

Payload Example

EventOccurrence Upcoming Webhook Payload

{
  "topic": "event_occurrence.upcoming",
  "webhook_id": 1,
  "business_id": 2,
  "data": {
    "event_occurrences": [
      {
        "id": 3,
        "event_id": 4,
        "name": "Class with Makeups",
        "description": null,
        "duration_in_minutes": 60.0,
        "service_id": 5,
        "service_type": "GroupClass",
        "location_id": 6,
        "room_id": 1,
        "room_name": "Main Room",
        "start_at": "2020-05-29 16:00:00 -0700",
        "end_at": "2020-05-29 17:00:00 -0700",
        "created_at": "2020-05-28 14:00:00 -0700",
        "updated_at": "2020-05-28 16:00:00 -0700",
        "updating": false,
        "timezone": "Pacific Time (US & Canada)",
        "attendance_complete": false,
        "visits_count": 4,
        "state": "active",
        "full": false,
        "visitors_can_view": false,
        "clients_can_view": true,
        "members_can_view": true,
        "clients_can_book": true,
        "members_can_book": true,
        "capacity_remaining": 18,
        "anonymous_staff": false,
        "staff_members": [
          {
            "id": 7,
            "name": "Nathan Doe"
          }
        ],
        "people": [
          {
            "id": 4,
            "name": "Kacie Dach"
          }
        ]
      }
    ]
  }
}

event_occurrence.created

Triggers whenever a new event occurrence is created.

Payload Example

EventOccurrence Created Webhook Payload

{
  "topic": "event_occurrence.created",
  "webhook_id": 1,
  "business_id": 2,
  "data": {
    "event_occurrences": [
      {
        "id": 3,
        "event_id": 4,
        "name": "Class with Makeups",
        "description": null,
        "duration_in_minutes": 60.0,
        "service_id": 5,
        "service_type": "GroupClass",
        "location_id": 6,
        "room_id": 1,
        "room_name": "Main Room",
        "start_at": "2020-05-29 16:00:00 -0700",
        "end_at": "2020-05-29 17:00:00 -0700",
        "created_at": "2020-05-28 14:00:00 -0700",
        "updated_at": "2020-05-28 16:00:00 -0700",
        "updating": false,
        "timezone": "Pacific Time (US & Canada)",
        "attendance_complete": false,
        "visits_count": 0,
        "state": "active",
        "full": false,
        "visitors_can_view": false,
        "clients_can_view": true,
        "members_can_view": true,
        "clients_can_book": true,
        "members_can_book": true,
        "capacity_remaining": 18,
        "anonymous_staff": false,
        "staff_members": [
          {
            "id": 7,
            "name": "Nathan Doe"
          }
        ],
        "people": [

        ]
      }
    ]
  }
}

event_occurrence.updated

Triggers whenever an event occurrence is updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
location_id
start_at
end_at
attendance_complete
visits_count
state

This topic supports previous values within data:

data

event_occurrences

array

Array of one event occurrence.

object

Previous values of the resource. The following are supported:

location_id	integer	Location's ID.
start_at	timestamp	Timestamp for when the event occurrence starts.
end_at	timestamp	Timestamp for when the event occurrence ends.
attendance_complete	boolean	Boolean value of whether event occurrence has had its attendance confirmed.
visits_count	integer	Integer value of the total amount of clients enrolled.
state	string	Event occurrence's state. One of [active, canceled, deleted, reserved].

Payload Example

EventOccurrence Updated Webhook Payload

{
  "topic": "event_occurrence.updated",
  "webhook_id": 1,
  "business_id": 2,
  "data": {
    "event_occurrences": [
      {
        "id": 3,
        "event_id": 4,
        "name": "Class with Makeups",
        "description": null,
        "duration_in_minutes": 60.0,
        "service_id": 5,
        "service_type": "GroupClass",
        "location_id": 6,
        "room_id": 1,
        "room_name": "Main Room",
        "start_at": "2020-05-29 16:00:00 -0700",
        "end_at": "2020-05-29 17:00:00 -0700",
        "created_at": "2020-05-28 14:00:00 -0700",
        "updated_at": "2020-05-28 16:00:00 -0700",
        "updating": false,
        "timezone": "Pacific Time (US & Canada)",
        "attendance_complete": false,
        "visits_count": 6,
        "state": "active",
        "full": false,
        "visitors_can_view": false,
        "clients_can_view": true,
        "members_can_view": true,
        "clients_can_book": true,
        "members_can_book": true,
        "capacity_remaining": 18,
        "anonymous_staff": false,
        "staff_members": [
          {
            "id": 7,
            "name": "Nathan Doe"
          }
        ],
        "people": [
          {
            "id": 4,
            "name": "Kacie Dach"
          }
        ]
      }
    ],
    "previous": {
      "start_at": "2020-05-29 18:00:00 -0700",
      "visits_count": 5,
      "updated_at": "2020-05-28 17:00:00 -0700"
    }
  }
}

event_occurrence.staff_member_updated

Triggers whenever an instructor is added, removed or changed.

This topic supports previous values within data:

data

event_occurrences

array

Array of one event occurrence.

object

Previous values of the resource. The following are supported:

staff_members

array

Array of people objects who are instructing this event occurrence. Empty if no instructor is currently assigned.

id	integer	Staff member's ID.
name	string	Staff member's name.

Payload Example

EventOccurrence Staff Member Updated Webhook Payload

{
  "topic": "event_occurrence.staff_member_updated",
  "webhook_id": 1,
  "business_id": 2,
  "data": {
    "event_occurrences": [
      {
        "id": 3,
        "event_id": 4,
        "name": "Class with Makeups",
        "description": null,
        "duration_in_minutes": 60.0,
        "service_id": 5,
        "service_type": "GroupClass",
        "location_id": 6,
        "room_id": 1,
        "room_name": "Main Room",
        "start_at": "2020-05-29 16:00:00 -0700",
        "end_at": "2020-05-29 17:00:00 -0700",
        "created_at": "2020-05-28 14:00:00 -0700",
        "updated_at": "2020-05-28 16:00:00 -0700",
        "updating": false,
        "timezone": "Pacific Time (US & Canada)",
        "attendance_complete": false,
        "visits_count": 6,
        "state": "active",
        "full": false,
        "visitors_can_view": false,
        "clients_can_view": true,
        "members_can_view": true,
        "clients_can_book": true,
        "members_can_book": true,
        "capacity_remaining": 18,
        "anonymous_staff": false,
        "staff_members": [
          {
            "id": 5,
            "name": "Nathan Doe"
          }
        ]
      }
    ],
    "previous": {
      "staff_members": [
        {
          "id": 7,
          "name": "Kacie Dach"
        }
      ]
    }
  }
}

Invoice

Core API resource payload url:

Desk

GET /api/v2/desk/invoices/:id

See the core api doc

Resource Attributes

data.invoices[0]

integer

The ID of the invoice.

invoice_number

string

A unique bill identifier for this business, a.k.a. bill number.

invoice_date

string

This invoice's due date.

total_cents

integer

The amount total in cents for this invoice.

total

string

The amount total in localized currency for this invoice.

outstanding_amount_cents

integer

The amount outstanding in cents.

outstanding_amount

string

The amount outstanding in localized currency.

discount_total_cents

integer

The sum of all discounts in cents.

discount_total

string

The sum of all discounts in localized currency.

adjustment_total_cents

integer

The sum of all adjustments in cents.

adjustment_total

string

The sum of all adjustments in localized currency.

included_tax_total_cents

integer

The sum of all included taxes in cents.

included_tax_total

string

The sum of all included taxes in localized currency.

additional_tax_total_cents

integer

The sum of all additional taxes in cents.

additional_tax_total

string

The sum of all additional taxes in localized currency.

currency

string

The currency ISO code.

state

string

The current state of the invoice. Either 'open', 'closed', 'canceled', 'cart', 'cart_hidden', or 'on_hold.'

state_events

array

An array of strings containing the valid state events when calling to update the invoice.

invoice_items

object

Information regarding the item the invoice is about

integer

The ID of the item the invoice is for.

name

string

The name of the item the invoice is for.

description

string

The full description of the item the invoice is for.

recipients

array

Array of people who received this item.

id	integer	The ID of the person who the invoice is for.
name	string	The full name of the person who the invoice is for.
email	string	The email address of the person who the invoice is for.

adjustments

array

Array of adjustments to the invoice item, documenting changes in the item within this invoice.

integer

The ID of the adjustment.

type

string

Possible values include: 'Adjustment' for the price, 'CreditAdjustment' for credit, 'Discount' for discounts, 'PriceOverride' for overrides on the price, 'ProrateAdjustment' for proration, and 'TaxAdjustment' for taxes.

name

string

The name for the adjustment.

created_at

string

The date the adjustment was created.

amount_cents

integer

Either the amount of the fixed price discount or the computed amount of the percent discount in cents.

amount

integer

Either the amount of the fixed price discount or the computed amount of the percent discount in localized currency.

percent

integer

Optional. The percentage, if it is a percent adjustment. This can be negative for TaxAdjustments.

source

object

Optional. The source of the invoice item adjustment

id	integer	The ID of the source.
type	string	The type of the source.

detail

object

Details regarding the item the invoice is for

id	integer	The ID the of details for the item.
type	string	The object type of the item, i.e 'Membership', 'SignupFee'.
start_date	string	Optional. The start date of the item.
count_description	string	Optional. How often the item is used.
extended_description	array	Optional. The extended description of the item.
initial_punchcard_count_description	string	Optional. How many punches the card starts with.
has_terms	boolean	Optional. True if the item has terms.
plan_product_id	integer	Optional. The ID for the product plan.
product_id	integer	Optional. The ID for the product.
retail_product_id	integer	Optional. The ID for the retail product.

service

object

Optional. The service the item falls under

id	integer	The ID of the service

payments

array

The payments that have already been made on the invoice

integer

The ID of the payment.

description

string

The description of the payment.

state

string

The state of the payment.

amount_cents

integer

The amount in cents of the payment.

amount

string

The amount in localized currency of the payment.

maximum_refund_cents

integer

The maximum amount refundable in cents of the payment.

maximum_refund

string

The maximum amount refundable in localized currency of the payment.

created_at

string

The date the payment was created.

voided_at

string

The date the payment was voided.

error_message

string

Optional. The error message for the payment if it failed.

refunds

object

Optional. The refunds for the payments

id	integer	The ID of the refund.
amount_cents	integer	The amount in cents of the refund.
amount	string	The amount in localized currency of the refund.
state	string	The state of the refund.
payment_id	int	The ID of the payment the refund is for.
description	string	The description of the refund.
created_at	string	The date the refund was created.
voided_at	string	The date the refund was voided.

payer

object

Optional. The person who paid the payment

id	integer	The ID of the person who the invoice is for.
name	string	The full name of the person who the invoice is for.
email	string	The email address of the person who the invoice is for.

person

object

Optional. Information regarding the person who the invoice is for

id	integer	The ID of the person attached to this invoice.
name	string	The name of the person attached to this invoice.
email	string	The email of the person attached to this invoice.

coupon

object

Optional. Information regarding a coupon for the invoice, if there is any

id	integer	The ID of the promotion.
code	string	The code for the promotion.
name	string	The name of the promotion.
description	string	The description of the promotion.
discount_percent	integer	Optional. The discount percent of the promotion.
discount_amount_cents	integer	Optional. The fixed amount discount in cents of the promotion.
discount_amount	integer	Optional. The fixed amount discount in localized currency of the promotion.

object

Optional. If this an UPDATE payload - additional information about the changed attributes

varies	object	Various details about the changed attributes of the invoice.

A Special Note about Invoice Topics

The webhook topic 'invoice.new' is suggested for most uses instead of 'invoice.created'.

The 'invoice.new' topic shields users from being exposed to some of the internal state changes that invoices go through during their lifecycle. For instance, a new invoice object is created every time a shopping cart is created - but most people aren't really interested in an invoice until it is in a billable or paid state.

invoice.new

The 'invoice.new' webhook topic is recommended as the best way to get invoices when they are created from an end user's perspective. It will trigger whenever an invoice is created or updated so long as the state the invoice is entering is NOT CART. The possible states for an invoice are: OPEN, CLOSED, CANCELLED, CART, CART_HIDDEN, ON_HOLD.

Payload Example

Invoice New Webhook Payload

{
  "topic": "invoice.new",
  "webhook_id": 4,
  "business_id": 1,
  "data": {
    "invoices": [
      {
        "id": 51,
        "invoice_number": "100059",
        "invoice_date": "2018-12-12",
        "total_cents": 11200,
        "total": "112.00",
        "outstanding_amount_cents": 0,
        "outstanding_amount": "0.00",
        "discount_total_cents": 0,
        "discount_total": "0.00",
        "adjustment_total_cents": -1200,
        "adjustment_total": "-12.00",
        "included_tax_total_cents": 0,
        "included_tax_total": "0.00",
        "additional_tax_total_cents": -200,
        "additional_tax_total": "-2.00",
        "state_events": [
          "reopen"
        ],
        "send_receipt": true,
        "receipt_email": null,
        "currency": "USD",
        "state": "closed",
        "has_tip": false,
        "has_commission_pay": false,
        "can_adjust_tip": false,
        "invoice_items": [
          {
            "id": 19,
            "name": "Class R",
            "description": "Class R",
            "discount_total_cents": 0,
            "discount_total": "0.00",
            "amount_cents": 10000,
            "amount": "100.00",
            "recipients": [
              {
                "name": "Apendaulla Dependable"
              }
            ],
            "adjustments": [
              {
                "id": 14,
                "type": "TaxAdjustment",
                "name": "Seattle",
                "percent": -10,
                "amount_cents": -1000,
                "amount": "-10.00",
                "source": {
                  "id": 1,
                  "type": "SalesTax"
                },
                "created_at": "2018-12-12T21:52:42Z"
              },
              {
                "id": 15,
                "type": "TaxAdjustment",
                "name": "King County",
                "percent": -2,
                "amount_cents": -200,
                "amount": "-2.00",
                "source": {
                  "id": 2,
                  "type": "SalesTax"
                },
                "created_at": "2018-12-12T21:52:42Z"
              }
            ],
            "detail": {
              "id": 20,
              "type": "Pack",
              "start_date": "2018-12-12",
              "count_description": "1 visit per Week",
              "extended_description": [
                "Starts on Dec 12",
                "for Apendaulla Dependable"
              ],
              "has_terms": false,
              "plan_product_id": 5,
              "product_id": 5
            },
            "commissionable": false,
            "compable": true
          }
        ],
        "payments": [
          {
            "id": 3,
            "description": "Cash",
            "state": "completed",
            "amount_cents": 11200,
            "amount": "112.00",
            "maximum_refund_cents": 11200,
            "maximum_refund": "112.00",
            "created_at": "2018-12-12T21:53:17Z",
            "voided_at": null,
            "is_voidable": false
          }
        ],
        "location": {
          "id": 1,
          "name": "Raushire",
          "slug": "raushire"
        },
        "created_by": {
          "id": 1,
          "name": "John Helpful",
          "email": "john.helpful@pike13.com"
        },
        "person": {
          "id": 56,
          "name": "Apendaulla Dependable",
          "email": null
        }
      }
    ]
  }
}

invoice.created

The 'invoice.created' webhook topic is not recommended for most users. It triggers every time an internal invoice record is created. For example, if someone starts shopping you would get a notification even if the shopping cart is later abandoned and what we call an "invoice" is never actually created in a billable state. Instead we recommend you use the 'invoice.new' trigger.

Payload Example

Invoice Created Webhook Payload

{
  "topic": "invoice.created",
  "webhook_id": 4,
  "business_id": 1,
  "data": {
    "invoices": [
      {
        "id": 58,
        "invoice_number": "100045",
        "invoice_date": "2012-09-03",
        "total_cents": 0,
        "total": "0.00",
        "outstanding_amount_cents": 0,
        "outstanding_amount": "0.00",
        "discount_total_cents": 0,
        "discount_total": "0.00",
        "adjustment_total_cents": 0,
        "adjustment_total": "0.00",
        "included_tax_total_cents": 0,
        "included_tax_total": "0.00",
        "additional_tax_total_cents": 0,
        "additional_tax_total": "0.00",
        "state_events": [
          "open",
          "cancel",
          "close"
        ],
        "send_receipt": true,
        "receipt_email": null,
        "currency": "USD",
        "state": "cart",
        "has_tip": false,
        "has_commission_pay": false,
        "can_adjust_tip": false,
        "invoice_items": [

        ],
        "payments": [

        ],
        "created_by": {
          "id": 1,
          "name": "Jane Doe",
          "email": "jane.doe@example.com"
        }
      }
    ]
  }
}

invoice.updated

Changes to these fields trigger an "invoice.updated" notification. Payment changes are handled by the Transactions webhook topic.
state	string	Possible values: open, closed, cancelled, cart, cart_hidden, on_hold
person	person	The assigned person { id, name, email }
receipt_email	string	email@example.com
location	object	{ id, name, slug }
commission_recipient	person	{ id, name, email }
tip_recipient	person	{ id, name, email }

Previous values supported by the "invoice.updated" topic
state	string	Possible values: open, closed, cancelled, cart, cart_hidden, on_hold
person	person	The assigned person { id, name, email }
receipt_email	string	email@example.com
location	object	{ id, name, slug }
commission_recipient	person	{ id, name, email }
tip_recipient	person	{ id, name, email }

Payload Example

Invoice Updated Webhook Payload

{
  "topic": "invoice.updated",
  "webhook_id": 3,
  "business_id": 1,
  "data": {
    "invoices": [
      {
        "id": 58,
        "invoice_number": "100045",
        "invoice_date": "2012-09-03",
        "total_cents": 1100,
        "total": "11.00",
        "outstanding_amount_cents": 0,
        "outstanding_amount": "0.00",
        "discount_total_cents": 0,
        "discount_total": "0.00",
        "adjustment_total_cents": -100,
        "adjustment_total": "-1.00",
        "included_tax_total_cents": 0,
        "included_tax_total": "0.00",
        "additional_tax_total_cents": -100,
        "additional_tax_total": "-1.00",
        "state_events": [
          "reopen"
        ],
        "send_receipt": false,
        "receipt_email": null,
        "currency": "USD",
        "state": "closed",
        "has_tip": false,
        "has_commission_pay": false,
        "can_adjust_tip": false,
        "invoice_items": [
          {
            "id": 31,
            "name": "t-shirt",
            "description": "t-shirt - size medium",
            "discount_total_cents": 0,
            "discount_total": "0.00",
            "amount_cents": 1000,
            "amount": "10.00",
            "recipients": [

            ],
            "adjustments": [
              {
                "id": 41,
                "type": "TaxAdjustment",
                "name": "Seattle",
                "created_at": "2019-02-20T16:59:24Z",
                "percent": -10.0,
                "amount_cents": -100,
                "amount": "-1.00",
                "source": {
                  "id": 1,
                  "type": "SalesTax"
                }
              }
            ],
            "detail": {
              "id": 3,
              "type": "Retail",
              "extended_description": [
                "size medium"
              ],
              "has_terms": false,
              "retail_product_id": 1
            },
            "commissionable": false,
            "compable": true
          }
        ],
        "payments": [
          {
            "id": 9,
            "description": "Cash",
            "state": "completed",
            "amount_cents": 1100,
            "amount": "11.00",
            "maximum_refund_cents": 1100,
            "maximum_refund": "11.00",
            "created_at": "2019-02-20T17:01:01Z",
            "voided_at": null,
            "is_voidable": true
          }
        ],
        "location": {
          "id": 1,
          "name": "Raushire",
          "slug": "raushire"
        },
        "created_by": {
          "id": 1,
          "name": "Jane Doe",
          "email": "jane.doe@example.com"
        }
      }
    ],
    "previous": {
      "state": 4,
      "updated_at": "2019-02-20T17:00:00Z"
    }
  }
}

Person

Core API resource payload url:

Desk

GET /api/v2/desk/people/:id

See the core api doc

Resource Attributes

data.people[0]

integer

Person's ID.

pronoun

string

Person's preferred pronouns.

first_name

string

Person's first name.

middle_name

string

Person's middle name.

last_name

string

Person's last name.

name

string

Person's full name.

string

Person's email address. Email address formatting is enforced.

is_member

boolean

Whether person is a member of the business.

address

string

Person's physical address.

phone

string

Person's phone number.

birthdate

date

Person's date of birth.

guardian_name

string

Full name of person's guardian.

guardian_email

string

Email address of person's guardian.

timezone

integer

Timezone of a person.

business_id

integer

ID of the business to which a person belongs.

updated_at

timestamp

Timestamp for when the person was last updated in the business.

deleted_at

timestamp

Timestamp for when the person was deleted from the business. Null if not deleted.

hidden_at

timestamp

Timestamp for when the person was hidden in the business. Null if not hidden.

joined_at

timestamp

Timestamp for when the person joined the business.

secondary_info_field

string

Client info that appears below this person's name when listing clients.

primary_staff_member

object

Optional. Staff information for this person.

id	integer	Staff member's person ID.
name	string	Name of staff member.

location

object

Optional. Location information for this person.

id	integer	The ID for this location.
name	integer	The name of this location.
slug	integer	The slug (unique string) for this location.

dependents

array

Not supported on person.created.

Array of people objects who are managed by the person. Empty if no such people are managed.

integer

Person's ID.

pronoun

string

Person's preferred pronouns.

first_name

string

Person's first name.

middle_name

string

Person's middle name.

last_name

string

Person's last name.

name

string

Person's full name.

is_member

boolean

Whether person is a member of the business.

string

Person's email address. Email address formatting is enforced.

address

string

Person's physical address.

phone

string

Person's phone number.

birthdate

date

Person's date of birth.

guardian_name

string

Full name of person's guardian.

guardian_email

string

Email address of person's guardian.

business_id

integer

ID of the business to which a person belongs.

timezone

integer

Timezone of a person.

updated_at

timestamp

Timestamp for the most recent update of a person.

deleted_at

timestamp

Timestamp for when the person was deleted from the business. Null if not deleted.

hidden_at

timestamp

Timestamp for when the person was hidden in the business. Null if not hidden.

joined_at

timestamp

Timestamp for when the person joined the business.

secondary_info_field

string

Client info that appears below this person's name when listing clients.

custom_fields

array

Array of person_custom_field objects with the following schema:

custom_field_id	integer	ID of the custom field.
id	integer	ID of person's custom field response.
name	string	Name of the custom field.
value	string	Value of the person's custom field response.

providers

array

Not supported on person.created.

Array of people objects who are account managers of the person. Empty if no account managers exist. Same JSON structure as dependents.

profile_photo

object

Not supported on person.created.

Optional. Shows url of profile photo if one is available.

x50	string	Url of profile photo, sized 50x50.
x100	string	Url of profile photo, sized 100x100.
x200	string	Url of profile photo, sized 200x200.
x400	string	Url of profile photo, sized 400x400.

person.created

Triggers when a new person is added to a business.

Payload Example

Person Created Webhook Payload

{
  "topic": "person.created",
  "webhook_id": 1,
  "business_id": 1,
  "data": {
    "people": [
      {
        "id": 10,
        "address": null,
        "birthdate": null,
        "business_id": 1,
        "deleted_at": null,
        "dependents": [

        ],
        "email": null,
        "pronoun": null,
        "first_name": "John",
        "guardian_email": null,
        "guardian_name": "Nathan Doe",
        "hidden_at": null,
        "is_member": false,
        "joined_at": "2019-02-19T23:24:02Z",
        "last_name": "Doe",
        "location": {
          "id": 30742,
          "name": "Example Business",
          "slug": "example-business"
        },
        "middle_name": null,
        "name": "John Doe",
        "phone": "123 456 7890",
        "primary_staff_member": {
          "id": 2,
          "name": "Joseph Cremin"
        },
        "providers": [

        ],
        "secondary_info_field": "No Membership",
        "timezone": "America/Los_Angeles",
        "updated_at": "2019-02-19T23:24:02Z"
      }
    ]
  }
}

person.updated

Triggers when a specific fields of a person are updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification

pronoun

string

Person's preferred pronouns.

first_name

string

Person's first name.

middle_name

string

Person's middle name.

last_name

string

Person's last name.

string

Person's email address. Email address formatting is enforced.

address

string

Person's physical address.

phone

string

Person's phone number.

birthdate

date

Person's date of birth.

guardian_name

string

Full name of person's guardian.

guardian_email

string

Email address of person's guardian.

joined_at

timestamp

Timestamp for when the person joined the business.

is_member

boolean

Whether person is a member of the business.

custom_fields

object

A notification will be sent whenever an individual person_custom_field object's value changes or is created for the person:

id	integer	ID of person's custom field response.
value	string	Value of the person's custom field response.

This topic supports previous values within data:

data

people

array

Array of one person updated in the business.

object

Previous values of the resource. The following are supported:

pronoun

string

Person's preferred pronouns.

first_name

string

Person's first name.

middle_name

string

Person's middle name.

last_name

string

Person's last name.

string

Person's email address. Email address formatting is enforced.

address

string

Person's physical address.

phone

string

Person's phone number.

birthdate

date

Person's date of birth.

guardian_name

string

Full name of person's guardian.

guardian_email

string

Email address of person's guardian.

is_member

boolean

Whether person is a member of the business.

updated_at

timestamp

Timestamp for when the person was last updated in the business.

hidden_at

timestamp

Timestamp for when the person was hidden in the business. Null if not hidden.

joined_at

timestamp

Timestamp for when the person joined the business.

primary_staff_member_id

integer

Person's staff member id

custom_fields

object

id	integer	ID of person's custom field response.
value	string	Value of the person's custom field response.

Payload Example

Person Updated Webhook Payload

{
  "topic": "person.updated",
  "webhook_id": 10,
  "business_id": 2,
  "data": {
    "people": [
      {
        "id": 3,
        "pronoun": null,
        "first_name": "Jaylon",
        "middle_name": null,
        "last_name": "Murazik",
        "guardian_name": null,
        "name": "Jaylon Murazik",
        "is_member": false,
        "joined_at": "2012-09-03T16:05:00Z",
        "phone": "1-971-448-7713",
        "email": "jaylon.murazik@pike13.com",
        "address": null,
        "secondary_info_field": "No Membership",
        "guardian_email": null,
        "timezone": "America/Los_Angeles",
        "business_id": 2,
        "updated_at": "2012-09-03T16:05:00Z",
        "deleted_at": null,
        "hidden_at": null,
        "birthdate": null,
        "custom_fields": [

        ],
        "dependents": [
          {
            "id": 4,
            "pronoun": null,
            "first_name": "Mckenzie",
            "middle_name": null,
            "last_name": "Jacobson",
            "guardian_name": "Jaylon Murazik",
            "name": "Mckenzie Jacobson",
            "is_member": false,
            "joined_at": "2012-09-03T16:05:00Z",
            "phone": "133-854-7150",
            "email": "jacobson.mckenzie@pike13.com",
            "address": null,
            "secondary_info_field": "No Membership",
            "guardian_email": "jaylon.murazik@pike13.com",
            "timezone": "America/Los_Angeles",
            "business_id": 2,
            "updated_at": "2012-09-03T16:05:00Z",
            "deleted_at": null,
            "hidden_at": null,
            "birthdate": null,
            "custom_fields": [

            ]
          }
        ],
        "providers": [

        ]
      }
    ],
    "previous": {
      "first_name": "Foster",
      "updated_at": "2012-09-02T16:05:00Z"
    }
  }
}

Person.deleted

Triggers when a person is deleted.

Payload Example

Person Deleted Webhook Payload

{
  "topic": "person.deleted",
  "webhook_id": 10,
  "business_id": 2,
  "data": {
    "people": [
      {
        "id": 9102342,
        "first_name": "John",
        "middle_name": "James",
        "last_name": "Miller",
        "email": "jjmiller@gmail.com",
        "updated_at": "2019-02-19T23:24:02Z",
        "created_at": "2019-02-19T23:24:02Z",
        "deleted_at": "2020-01-29T11:31:18Z"
      }
    ]
  }
}

Person Plan

Resource Attributes

data.person_plans[0]

integer

ID of the person_plan association.

created_at

timestamp

Timestamp for when this person became associated with this plan.

deactivated_at

timestamp

Timestamp for when this person was removed from this plan, if applicable.

exhausted_at

timestamp

Timestamp for when this person_plan was exhausted, if applicable.

updated_at

timestamp

Timestamp for when this person_plan was updated, if applicable.

person

object

Details of the person for this person_plan.

id	integer	ID for this person.
name	string	Name of this person.
email	string	Email for this person.

plan

object

Details of the plan for this person_plan.

id	integer	ID for this plan.
description	string	Description of this plan.
type	string	Type of this plan. One of ['Pack', 'Prepaid', 'Membership'].
plan_product_id	integer	ID of product associated with this plan.
count	integer	Maximium count (limit) for the number of punches for this plan during the 'limit_period'.
staff_member_id	integer	Staff Member ID for this plan.
location_id	integer	Location ID for this plan.
price	string	Price formatted in currency units for this plan.
price_cents	integer	Price in cents for this plan.
limit_period	string	Limit period for this plan if any. One of ['weekly', 'monthly'].
start_date	date	Start date for this plan.
end_date	date	End date for this plan.
cancelled_at	timestamp	Timestamp for when this plan was cancelled, if applicable.
updated_at	timestamp	Timestamp for when this plan was updated.
created_at	timestamp	Timestamp for when this plan was created.

plan_product

object

Details of the plan product for this person_plan.

id	integer	ID for this plan_product.
consider_member	boolean	True if clients who buy this person_plan are considered members

person_plan.created

Triggers whenever a new person_plan is created.

Payload Example

PersonPlan Created Webhook Payload

{
  "topic": "person_plan.created",
  "business_id": 1,
  "data": {
    "person_plans": [
      {
        "id": 1,
        "created_at": "2012-09-03T09:05:01Z",
        "deactivated_at": null,
        "exhausted_at": null,
        "updated_at": "2012-09-03T09:05:01Z",
        "person": {
          "id": 1,
          "name": "Kiel Kuhic",
          "email": "kuhic_kiel@pike13.com"
        },
        "plan": {
          "id": 1,
          "description": "Super Cool Plan",
          "type": "Prepaid",
          "plan_product_id": 2,
          "count": 1,
          "staff_member_id": 2,
          "location_id": null,
          "price": "10,000.00",
          "price_cents": "1000000",
          "limit_period": "weekly",
          "start_date": "2012-09-03",
          "end_date": "2012-10-02",
          "cancelled_at": null,
          "updated_at": "2012-09-03T09:05:01Z",
          "created_at": "2012-09-03T09:05:01Z"
        },
        "plan_product": {
          "id": 2,
          "consider_member": true
        }
      }
    ]
  }
}

person_plan.updated

Triggers whenever a person_plan is updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
person_id	integer	The person on the plan
deactivated_at	timestamp	The date this plan was deactivated
exhausted_at	string	The date the person plan was exhausted

This topic supports previous values within data:

data

person_plans

array

Array of one person plan updated in the business.

object

Previous values of the resource. The following are supported:

person_id	integer	ID of the person for this person_plan
deactivated_at	timestamp	The date this plan was deactivated
exhausted_at	string	The date the person plan was exhausted
updated_at	string	The date the person plan was last updated

Payload Example

PersonPlan Updated Webhook Payload

{
  "topic": "person_plan.updated",
  "business_id": 1,
  "data": {
    "person_plans": [
      {
        "id": 1,
        "created_at": "2012-09-03T09:05:01Z",
        "deactivated_at": "2012-09-02T01:21:22Z",
        "exhausted_at": "2012-08-01T09:15:21Z",
        "updated_at": "2012-09-03T09:05:01Z",
        "person": {
          "id": 1,
          "name": "Kiel Kuhic",
          "email": "kuhic_kiel@pike13.com"
        },
        "plan": {
          "id": 1,
          "description": "Super Cool Plan",
          "type": "Prepaid",
          "plan_product_id": 2,
          "count": 1,
          "staff_member_id": 2,
          "location_id": null,
          "price": "10,000.00",
          "price_cents": "1000000",
          "limit_period": "weekly",
          "start_date": "2012-09-03",
          "end_date": "2012-10-02",
          "cancelled_at": null
        },
        "plan_product": {
          "id": 2,
          "consider_member": true
        }
      }
    ],
    "previous": {
      "person_id": 8,
      "deactivated_at": null,
      "exhausted_at": null,
      "updated_at": "2019-02-20T17:00:00Z"
    }
  }
}

Plan

Resource Attributes

data.plans[0]

integer

ID for this plan.

description

string

Description of this plan.

type

string

Type of this plan. One of ['Pack', 'Prepaid', 'Membership'].

plan_product_id

integer

ID of product associated with this plan.

count

integer

Maximium count (limit) for the number of punches for this plan during the 'limit_period'.

staff_member_id

integer

Staff Member ID for this plan.

location_id

integer

Location ID for this plan.

price

string

Price formatted in currency units for this plan.

price_cents

integer

Price in cents for this plan.

limit_period

string

Limit period for this plan if any. One of ['weekly', 'monthly'].

start_date

date

Start date for this plan.

end_date

date

End date for this plan.

cancelled_at

timestamp

Timestamp for when this plan was cancelled, if applicable.

updated_at

timestamp

Timestamp for when this plan was updated.

created_at

timestamp

Timestamp for when this plan was created.

people

array

Array of people objects who are on this plan. Empty if there are none.

id	integer	ID for this person.
name	string	Name of this person.
email	string	Email for this person.

plan.updated

Triggers when specific fields of a plan are updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
description
price_cents
count
staff_member_id
limit_period
start_date
end_date
cancelled_at

This topic supports previous values within data:

data

plans

array

Array of one plan updated in the business.

object

Previous values of the resource. The following are supported:

description	string	Description of this plan.
price	string	Price formatted in currency units for this plan.
price_cents	integer	Price in cents for this plan.
count	integer	Maximium count (limit) for the number of punches for this plan during the 'limit_period'.
staff_member_id	integer	Staff Member ID for this plan.
limit_period	string	Limit period for this plan if any. One of ['weekly', 'monthly'].
start_date	date	Start date for this plan.
end_date	date	End date for this plan.
cancelled_at	timestamp	Timestamp for when this plan was cancelled, if applicable.
updated_at	timestamp	Timestamp for when this plan was updated.

Payload Example

Plan Updated Webhook Payload

{
  "topic": "plan.updated",
  "business_id": 1,
  "data": {
    "plans": [
      {
        "id": 1,
        "description": "Prepaid plan for 2 people",
        "type": "Prepaid",
        "plan_product_id": 3,
        "count": 1,
        "staff_member_id": null,
        "location_id": null,
        "price_cents": 10000,
        "price": "10,000.00",
        "limit_period": "weekly",
        "start_date": "2014-04-01",
        "end_date": "2014-04-02",
        "cancelled_at": "2012-09-03T08:05:01Z",
        "updated_at": "2012-09-03T09:05:01Z",
        "created_at": "2012-09-03T09:05:01Z",
        "people": [
          {
            "id": 1,
            "name": "Lera Murphy",
            "email": "lera.murphy@pike13.com"
          },
          {
            "id": 2,
            "name": "Derrick Halvorson",
            "email": "halvorson_derrick@pike13.com"
          }
        ]
      }
    ],
    "previous": {
      "description": "previous",
      "price_cents": 111,
      "count": 111,
      "limit_period": "previous",
      "start_date": "2012-09-02",
      "end_date": "2012-09-02",
      "cancelled_at": null,
      "staff_member_id": 111,
      "updated_at": "2012-09-03T08:05:01Z"
    }
  }
}

plan.ended

Triggers when a plan is cancelled or when its end date has passed.

Payload Example

Plan Ended Webhook Payload

{
  "topic": "plan.ended",
  "business_id": 1,
  "data": {
    "plans": [
      {
        "id": 1,
        "description": "Prepaid plan for 2 people",
        "type": "prepaid",
        "plan_product_id": 3,
        "count": 1,
        "staff_member_id": null,
        "location_id": null,
        "price_cents": 10000,
        "price": "100.00",
        "limit_period": "weekly",
        "start_date": "2012-09-04",
        "end_date": "2012-09-03",
        "cancelled_at": "2012-09-03t16:05:01z",
        "updated_at": "2012-09-03t16:05:01z",
        "created_at": "2012-09-03t16:05:01z",
        "people": [
          {
            "id": 1,
            "name": "jarrett jast",
            "email": "jast_jarrett@pike13.com"
          },
          {
            "id": 2,
            "name": "elissa keeling",
            "email": "keeling_elissa@pike13.com"
          }
        ]
      }
    ]
  }
}

Plan Hold

Resource Attributes

data.plan_holds[0]
id	integer	ID of the plan hold.
start_date	date	Date the plan hold starts.
end_date	date	Date the plan hold ends.
plan_id	integer	ID of the associated plan.
created_at	timestamp	Timestamp for when the plan hold was created.
updated_at	timestamp	Timestamp for when the plan hold was last updated.

plan_hold.created

Triggers whenever a new plan hold is created.

Payload Example

Plan Hold Created Webhook Payload

{
  "topic": "plan_hold.created",
  "business_id": 2,
  "webhook_id": 5,
  "data": {
    "plan_holds": [
      {
        "id": 123,
        "start_date": "2020-07-03",
        "end_date": "2020-07-06",
        "plan_id": 406,
        "created_at": "2020-07-02T19:01:27Z",
        "updated_at": "2020-07-02T19:01:27Z"
      }
    ]
  }
}

plan_hold.updated

Triggers whenever a plan hold is updated.

Payload Example

Plan Hold Updated Webhook Payload

{
  "topic": "plan_hold.updated",
  "business_id": 2,
  "webhook_id": 9,
  "data": {
    "plan_holds": [
      {
        "id": 168,
        "start_date": "2020-07-08",
        "end_date": "2020-07-09",
        "plan_id": 282,
        "created_at": "2020-07-09T20:32:55Z",
        "updated_at": "2020-07-10T20:33:45Z"
      }
    ],
    "previous": {
      "end_date": null,
      "updated_at": "2020-07-09T20:32:55Z"
    }
  }
}

plan_hold.deleted

Triggers whenever a plan hold is deleted.

Payload Example

Plan Hold Deleted Webhook Payload

{
  "topic": "plan_hold.deleted",
  "business_id": 2,
  "webhook_id": 8,
  "data": {
    "plan_holds": [
      {
        "id": 75,
        "start_date": "2020-06-09",
        "end_date": "2020-06-10",
        "plan_id": 303,
        "created_at": "2020-06-09T20:42:38Z",
        "updated_at": "2020-06-11T03:41:58Z"
      }
    ]
  }
}

Punchcard

Punchcards track the amount of event occurrences the people associated with the punchcard can attend. A new punchcard starts every week if the plan is a weekly plan, every month if the plan is a monthly plan, etc.

Resource Attributes

data.punchcards[0]

integer

The punchcard's ID.

count

integer

The number of punches provided by the punchcard.

remaining

integer

The number of punches remaining on the punchcard.

start_date

date

The first day the punchcard is active.

end_date

date

The last day the punchcard is active.

people

object

id	integer	Person's ID.
name	string	Person's full name.
email	string	Person's email address. Email address formatting is enforced.

plan

object

Details of the associated plan.

id	integer	ID for this plan.
description	string	Description of this plan.
type	string	Type of this plan. One of ['Pack', 'Prepaid', 'Membership'].
count	integer	The number of punches each punchcard starts with for the duration of the limit period.
limit_period	string	Limit period for this plan if any (e.g. 'weekly', 'monthly'). The 'count' variable relates to this time period.

updated_at

timestamp

Timestamp for when the punchcard was last updated.

punchcard.started

Triggers when a punchcard becomes active for the current limit period.

Payload Example

Punchcard Started Webhook Payload

{
  "topic": "punchcard.started",
  "business_id": 1,
  "data": {
    "punchcards": [
      {
        "id": 1,
        "count": 10,
        "remaining": 10,
        "start_date": "2012-08-31",
        "end_date": "2012-09-06",
        "people": [
          {
            "id": 1,
            "name": "Zula Jacobi",
            "email": "zula.jacobi@example.com"
          }
        ],
        "plan": {
          "id": 1,
          "name": "Summer Strong",
          "description": "",
          "type": "Membership",
          "count": 1,
          "limit_period": "week"
        },
        "updated_at": "2012-09-03T09:05:02Z"
      }
    ]
  }
}

punchcard.updated

Triggers when a certain properties of a punchcard are updated.

The specific list of fields that trigger an update are:

Changes to these fields trigger a notification
count
remaining
start_date
end_date

data

people

array

Array of one updated punchcard.

object

Previous values of the resource. The following are supported:

count	integer	The number of punches provided by the punchcard.
remaining	integer	The number of punches remaining on the punchcard.
start_date	date	The first day the punchcard is active.
end_date	date	The last day the punchcard is active.
updated_at	timestamp	Timestamp for when the punchcard was last updated.

punchcard.updated

Triggers when a punchcard is updated.

Payload Example

Punchcard Updated Webhook Payload

{
  "topic": "punchcard.updated",
  "business_id": 80,
  "data": {
    "punchcards": [
      {
        "id": 77,
        "count": 5,
        "remaining": 5,
        "start_date": "2012-08-31",
        "end_date": "2012-09-02",
        "people": [
          {
            "id": 117,
            "name": "Nicholaus Greenholt",
            "email": "nicholaus_greenholt@example.com"
          }
        ],
        "plan": {
          "id": 77,
          "name": "MyString",
          "description": "MyString",
          "type": "Membership",
          "count": 1,
          "limit_period": "week"
        },
        "updated_at": "2012-09-03T09:05:46Z"
      }
    ],
    "previous": {
      "count": 10,
      "end_date": "2012-09-06",
      "remaining": 10,
      "updated_at": "2012-09-03T09:05:02Z"
    }
  }
}

punchcard.deleted

Triggers when a punchcard is deleted.

Payload Example

Punchcard Deleted Webhook Payload

{
  "topic": "punchcard.deleted",
  "business_id": 1,
  "data": {
    "punchcards": [
      {
        "id": 1,
        "count": 10,
        "remaining": 10,
        "start_date": "2012-08-31",
        "end_date": "2012-09-06",
        "people": [
          {
            "id": 1,
            "name": "Zula Jacobi",
            "email": "zula.jacobi@example.com"
          }
        ],
        "plan": {
          "id": 1,
          "name": "Summer Strong",
          "description": "",
          "type": "Membership",
          "count": 1,
          "limit_period": "week"
        },
        "updated_at": "2012-09-03T09:05:02Z"
      }
    ]
  }
}

Transaction

By subscribing to a transaction topic, you will be notified of two transaction types: payments and refunds. Check the data.transactions[0].type to differentiate.

Resource Attributes

data.transactions[0]

integer

The transaction's ID.

invoice_id

integer

ID of the associated invoice.

currency_code

string

The currency ISO code.

amount_cents

integer

The amount in cents of the transaction.

amount

string

The amount in localized currency of the transaction.

error_message

string

The error message for the transaction if it failed.

description

string

The description of the transaction.

voided_at

timestamp

The date the transaction was voided.

payment_type_id

integer

The type id of the available payment method.

type

string

Type is one of ['Payment', 'Refund'].

settled

boolean

Whether transaction has settled according to the payment gateway. Settled transactions cannot be voided.

state

string

One of ['failed', 'processing', 'completed', 'checkout']

uuid

UUID of the transaction.

autobill

boolean

Whether or not this transaction is on autobill.

payment_id

integer

ID of the payment. Only included if the transaction is a Refund.

external_transaction_id

integer

ID of the transaction according to the external transaction processor.

payment_type

string

Type of payment. One of ['cash', 'check', 'creditcard', 'ach', 'comp', 'free', 'external_creditcard', 'square', 'paypal', 'external', 'credit'].

created_at

timestamp

Timestamp for when transaction was created.

updated_at

timestamp

Timestamp for when transaction was last updated.

invoice

object

Details of the associated invoice.

id	integer	ID of the invoice.
total_cents	string	The amount total in cents for this invoice.
total	string	The amount total in localized currency for this invoice.
state_events	string	An array of strings containing the valid state events when calling to update the invoice.
send_receipt	string	Was a receipt email sent?
receipt_email	string	The email address the invoice was sent to, if any.
currency	string	The type of currency the invoice is charged in, i.e 'USD'.
state	string	The current state of the invoice. Either 'open', 'closed', 'canceled', 'cart', 'cart_hidden', or 'on_hold.'

transaction.created

Triggers when a new transaction is created.

Payload Example

Transaction Created Webhook Payload

{
  "topic": "transaction.created",
  "webhook_id": 11,
  "business_id": 1,
  "data": {
    "transactions": [
      {
        "id": 1,
        "invoice_id": 1,
        "currency_code": "USD",
        "amount_cents": 10000,
        "amount": "100.00",
        "error_message": null,
        "description": "Stored Visa 1111",
        "voided_at": null,
        "payment_type_id": 3,
        "type": "Payment",
        "settled": false,
        "state": "checkout",
        "uuid": "c8421956-fcef-412c-bc1f-92b7b2dd7156",
        "autobill": false,
        "external_transaction_id": "abc123",
        "payment_type": "creditcard",
        "created_at": "2012-09-03T09:05:02Z",
        "updated_at": "2012-09-03T09:05:02Z",
        "invoice": {
          "id": 1,
          "total_cents": 10000,
          "state_events": [
            "reopen"
          ],
          "send_receipt": false,
          "receipt_email": "john@example.com",
          "currency": "USD",
          "state": "closed"
        }
      }
    ]
  }
}

transaction.updated

Triggers when a certain properties of a transaction are updated.

The specific list of fields that trigger an update are:

Changes to these fields trigger a notification
invoice_id
currency_code
amount_cents
error_message
description
voided_at
payment_type_id
type
settled
state
uuid
autobill
payment_id
external_transaction_id
payment_type

data

people

array

Array of one updated transaction.

object

Previous values of the resource. The following are supported:

invoice_id	integer	ID of the associated invoice.
currency_code	string	The currency ISO code.
amount_cents	integer	The amount in cents of the transaction.
error_message	string	The error message for the transaction if it failed.
description	string	The description of the transaction.
voided_at	timestamp	The date the transaction was voided.
payment_type_id	integer	The type id of the available payment method.
type	string	Type is one of ['Payment', 'Refund'].
settled	boolean	Whether transaction has settled according to the payment gateway. Settled transactions cannot be voided.
state	string	One of ['failed', 'processing', 'completed', 'checkout']
uuid	uuid	UUID of the transaction.
autobill	boolean	Whether or not this transaction is on autobill.
payment_id	integer	ID of the payment. Only included if the transaction is a Refund.
external_transaction_id	integer	ID of the transaction according to the external transaction processor.
payment_type	string	Type of payment. One of ['cash', 'check', 'creditcard', 'ach', 'comp', 'free', 'external_creditcard', 'square', 'paypal', 'external', 'credit'].
updated_at	timestamp	Timestamp for when transaction was last updated.

Payload Example

Transaction Updated Webhook Payload

{
  "topic": "transaction.updated",
  "webhook_id": 12,
  "business_id": 2,
  "data": {
    "transactions": [
      {
        "id": 60,
        "invoice_id": 57,
        "currency_code": "USD",
        "amount_cents": 900,
        "amount": "9.00",
        "error_message": null,
        "description": "Cash",
        "payment_type_id": 1,
        "type": "Refund",
        "settled": true,
        "state": "completed",
        "uuid": "0e7c369c-c4c9-439d-a8eb-2a95bdb53789",
        "autobill": false,
        "payment_id": 59,
        "external_transaction_id": null,
        "payment_type": "cash",
        "voided_at": "2019-03-22T19:43:23Z",
        "created_at": "2019-03-22T19:32:23Z",
        "updated_at": "2019-03-22T19:43:23Z",
        "invoice": {
          "id": 57,
          "total_cents": 900,
          "state_events": [
            "reopen"
          ],
          "send_receipt": false,
          "receipt_email": "john@example.com",
          "currency": "USD",
          "state": "closed"
        }
      }
    ],
    "previous": {
      "voided_at": null,
      "updated_at": "2019-03-22T19:32:23Z"
    }
  }
}

Visit

Core API resource payload url:

Desk

GET /api/v2/desk/visits/:id

See the core api doc

Resource Attributes

data.visits[0]

integer

The visit's ID.

person_id

integer

ID of the associated person.

event_occurrence_id

integer

ID of the associated event occurrence.

state

string

Status of the visit. One of ['registered', 'reserved', 'noshowed', 'late_canceled', or 'completed']

registered_at

timestamp

Timestamp for when visit was registered. Typically, this is when the visit was created.

completed_at

timestamp

Timestamp for when visit was marked as complete by a staff member.

noshow_at

timestamp

Timestamp for when visit was marked as no-show by a staff member.

cancelled_at

timestamp

Timestamp for when visit was marked as a late cancel by a staff member.

created_at

timestamp

Timestamp for when visit was created.

updated_at

timestamp

Timestamp for when visit was last updated.

paid

boolean

True if this visit has been paid for.

paid_for_by

string

Description of the plan used to pay for the visit.

punch_id

integer

The id of the punch if present.

only_staff_can_cancel

boolean

True if only staff can cancel this visit.

event_occurrence

object

Details of the associated event_occurrence.

integer

ID of the event occurrence.

name

string

Name of the event occurrence.

state

string

One of ['reserved', 'active', 'cancelled', 'deleted'].

start_at

timestamp

Timestamp for when event occurrence begins.

end_at

timestamp

Timestamp for when event occurrence ends.

service_id

integer

ID of the associated service.

event_id

integer

ID of the associated event.

location_id

integer

ID of the associated location.

staff_members

array

Details of the associated list of staff members.

id	integer	ID of the staff member.
name	string	Name of the staff member.
has_profile	boolean	True if staff member has a profile.

person

object

Details of the associated person.

id	integer	ID of the person.
name	string	Name of the person.
email	string	Email of the person.

A Special Note about Visit Topics

The webhook topic 'visit.new' is suggested for most uses instead of 'visit.created'.

The 'visit.new' topic shields users from being exposed to some of the internal state changes that visits go through during their lifecycle. For instance, a new visit object is created in a "reserved" state before the user has paid for their registration. Most users will be interested in a visit once it's been "booked."

visit.new

Triggers when a new visit is created in a state other than "reserved." Also triggers when a visit transitions from "reserved" to "registered", "completed", "noshowed", or "late_cancel."

Payload Example

Visit New Webhook Payload

{
  "topic": "visit.new",
  "business_id": 1,
  "data": {
    "visits": [
      {
        "id": 1,
        "person_id": 1,
        "event_occurrence_id": 1,
        "state": "registered",
        "status": "enrolled",
        "registered_at": "2012-09-03T09:05:01Z",
        "completed_at": null,
        "noshow_at": null,
        "cancelled_at": null,
        "created_at": "2012-09-03T09:05:01Z",
        "paid": false,
        "paid_for_by": null,
        "punch_id": null,
        "only_staff_can_cancel": false,
        "event_occurrence": {
          "id": 1,
          "name": "Appointment A",
          "state": "active",
          "start_at": "2012-09-05T09:05:00Z",
          "end_at": "2012-09-05T09:35:00Z",
          "service_id": 1,
          "event_id": 1,
          "location_id": 2,
          "staff_members": [
            {
              "id": 2,
              "name": "Summer Stiedemann",
              "has_profile": true
            }
          ]
        },
        "person": {
          "id": 1,
          "name": "Andy Graham",
          "email": "graham_andy@pike13.com"
        }
      }
    ]
  }
}

visit.created

Triggers whenever a new visit is created, including those in a pre-booked "reserved" state.

Payload Example

Visit Created Webhook Payload

{
  "topic": "visit.created",
  "business_id": 1,
  "data": {
    "visits": [
      {
        "id": 1,
        "person_id": 1,
        "event_occurrence_id": 1,
        "state": "registered",
        "status": "enrolled",
        "registered_at": "2012-09-03T09:05:01Z",
        "completed_at": null,
        "noshow_at": null,
        "cancelled_at": null,
        "created_at": "2012-09-03T09:05:01Z",
        "updated_at": "2012-09-03T09:05:01Z",
        "paid": false,
        "paid_for_by": null,
        "punch_id": null,
        "only_staff_can_cancel": false,
        "event_occurrence": {
          "id": 1,
          "name": "Appointment A",
          "state": "active",
          "start_at": "2012-09-05T09:05:00Z",
          "end_at": "2012-09-05T09:35:00Z",
          "service_id": 1,
          "event_id": 1,
          "location_id": 2,
          "staff_members": [
            {
              "id": 2,
              "name": "Summer Stiedemann",
              "has_profile": true
            }
          ]
        },
        "person": {
          "id": 1,
          "name": "Andy Graham",
          "email": "graham_andy@pike13.com"
        }
      }
    ]
  }
}

visit.deleted

Triggers when a visit is deleted.

Payload Example

Visit Deleted Webhook Payload

{
  "topic": "visit.deleted",
  "business_id": 1,
  "data": {
    "visits": [
      {
        "id": 1,
        "person_id": 1,
        "event_occurrence_id": 1,
        "state": "registered",
        "status": "enrolled",
        "registered_at": "2012-09-03T09:05:01Z",
        "completed_at": null,
        "noshow_at": null,
        "cancelled_at": null,
        "created_at": "2012-09-03T09:05:01Z",
        "updated_at": "2012-09-03T09:05:01Z",
        "paid": false,
        "paid_for_by": null,
        "punch_id": null,
        "only_staff_can_cancel": false,
        "event_occurrence": {
          "id": 1,
          "name": "Appointment A",
          "state": "active",
          "start_at": "2012-09-05T09:05:00Z",
          "end_at": "2012-09-05T09:35:00Z",
          "service_id": 1,
          "event_id": 1,
          "location_id": 2,
          "staff_members": [
            {
              "id": 2,
              "name": "Summer Stiedemann",
              "has_profile": true
            }
          ]
        },
        "person": {
          "id": 1,
          "name": "Andy Graham",
          "email": "graham_andy@pike13.com"
        }
      }
    ]
  }
}

visit.updated

Triggers when specific fields of a visit are updated.

The specifc list of fields that trigger an update are:

Changes to these fields trigger a notification
state	string	Status of the visit. One of ['registered', 'reserved', 'noshowed', 'late_canceled', or 'completed']
completed_at	timestamp	Timestamp for when visit was marked as complete by a staff member.
noshow_at	timestamp	Timestamp for when visit was marked as no-show by a staff member.
cancelled_at	timestamp	Timestamp for when visit was marked as a late cancel by a staff member.
punch_id	integer	The id of the punch if present.

This topic supports previous values within data:

data

visits

array

Array of one visit updated in the business.

object

Previous values of the resource. The following are supported:

state	string	Status of the visit. One of ['registered', 'reserved', 'noshowed', 'late_canceled', or 'completed']
completed_at	timestamp	Timestamp for when visit was marked as complete by a staff member.
noshow_at	timestamp	Timestamp for when visit was marked as no-show by a staff member.
cancelled_at	timestamp	Timestamp for when visit was marked as a late cancel by a staff member.
punch_id	integer	The id of the punch if present.
updated_at	timestamp	Timestamp for when visit was last updated.

Payload Example

Visit Updated Webhook Payload

{
  "topic": "visit.updated",
  "business_id": 2,
  "data": {
    "visits": [
      {
        "id": 2,
        "person_id": 3,
        "event_occurrence_id": 2,
        "state": "registered",
        "status": "enrolled",
        "registered_at": "2012-09-03T09:05:00Z",
        "completed_at": null,
        "noshow_at": null,
        "cancelled_at": null,
        "created_at": "2012-09-03T09:05:00Z",
        "updated_at": "2012-09-03T09:06:00Z",
        "paid": false,
        "paid_for_by": null,
        "punch_id": null,
        "only_staff_can_cancel": false,
        "event_occurrence": {
          "id": 2,
          "name": "Appointment A",
          "state": "active",
          "start_at": "2012-09-05T09:05:00Z",
          "end_at": "2012-09-05T09:35:00Z",
          "service_id": 2,
          "event_id": 2,
          "location_id": 4,
          "staff_members": [
            {
              "id": 4,
              "name": "Stanford Donnelly",
              "has_profile": true
            }
          ]
        },
        "person": {
          "id": 3,
          "name": "Ottilie Roberts",
          "email": "ottilie_roberts@pike13.com"
        }
      }
    ],
    "previous": {
      "completed_at": "2012-09-03T09:05:00Z",
      "state": "completed",
      "updated_at": "2012-09-03T09:05:00Z"
    }
  }
}

Webhook

Represents a subscription to a topic for changes within a business. Franchises will be automatically notified of changes in all franchisees provided the franchise has created a webhook with a relevant topic. Every webhook endpoint is scoped by the access token and the business.

The subscription endpoint conforms to JSON API version 1.0.

GET /api/v3/webhooks

Returns all webhooks created by an account and scoped by the subdomain.

Show curl example

REQUEST
$ curl https://mybiz.pike13.com/api/v3/webhooks \
  -H "Authorization: Bearer XXXXXXXXXXXXXXX"
RESPONSE
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": [
    {
      "id": "2",
      "type": "webhooks",
      "links": {
        "self": "http://mybiz.pike13.com/api/v3/webhooks/2"
      },
      "attributes": {
        "account_id": 1,
        "business_id": 2,
        "topic": "person.created",
        "target": "https://target.example.com",
        "name": "New Client",
        "description": "Webhook for integration with my other service"
      }
    }
  ]
}

GET /api/v3/webhooks/:id

Returns a specific webhook.

POST /api/v3/webhooks

Create a webhook. account_id and business_id are not directly settable.

Required Attributes
topic	string	Must be a valid topic.
target	https url	An endpoint for Pike13 servers to POST a payload to.

Optional Attributes
name	string	A name for the webhook.
description	string	Description.

Show curl example

REQUEST
$ curl -X POST https://mybiz.pike13.com/api/v3/webhooks \
-H 'Authorization: Bearer XXXXXX' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
  "data": {
    "type": "webhooks",
      "attributes": {
        "target": "https://target.example.com",
        "topic": "person.created"
      }
    }
  }'
RESPONSE
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "5",
    "type": "webhooks",
    "links": {
      "self": "https://mybiz.pike13.com/api/v3/webhooks/5"
    },
    "attributes": {
      "account_id": 1,
      "business_id": 2,
      "topic": "person.created",
      "target": "https://target.example.com",
      "name": null,
      "description": null
    }
  }
}

PATCH /api/v3/webhooks/:id

Update a specific webhook. account_id and business_id are immutable.

Show curl example

REQUEST
$ curl -X PATCH https://mybiz.pike13.com/api/v3/webhooks/2 \
-H 'Authorization: Bearer XXXXXX' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
  "data": {
    "id": "2",
    "type": "webhooks",
      "attributes": {
        "target": "https://other.target.com"
      }
    }
  }'
RESPONSE
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "2",
    "type": "webhooks",
    "links": {
      "self": "https://mybiz.pike13.com/api/v3/webhooks/2"
    },
    "attributes": {
      "account_id": 1,
      "business_id": 2,
      "topic": "person.created",
      "target": "https://other.target.com",
      "name": null,
      "description": null
    }
  }
}

DELETE /api/v3/webhooks/:id

Deletes a specific webhook.

Show curl example

REQUEST
$ curl -X DELETE https://mybiz.pike13.com/api/v3/webhooks/2 \
-H 'Authorization: Bearer XXXXXX'
RESPONSE
HTTP/1.1 204 No Content

POST bodies

Notifications are sent within HTTP POST bodies. The common format for notifications hitting target servers is


NOTIFICATION PAYLOAD

POST https://target.example.com/
Content-Type: application/json

{
  "topic": "person.created",
  "data": { <topic fields> },
  "target_url": "https://target.example.com",
  "webhook_id": 1
}

Where the supported fields are documented for each topic. If the webhook is a <resource>.updated topic:


TOPIC FIELDS (changed exists only on *.updated topics)

{
  ...Supported fields for the topic,
  "changed": {<previous states of the corresponding field>}
}

A full example of a person.updated payload illustrates that the previous name for a person was "John" but was updated to "Gary":


EXAMPLE: person.updated payload

{
  "topic": "person.updated",
  "data": {
    "people": [
      {
        "id": 1,
        "first_name": "Gary",
        "middle_name": null,
        "last_name": "Turcotte",
        "email": "turcotte_raegan@pike13.com",
        "account_id": null,
        "created_at": "2012-09-03T09:05:00.468-07:00",
        "updated_at": "2012-09-03T09:08:53.337-07:00",
        "business_id": 1,
        "is_client": true,
        "address": null,
        "phone": "(534)052-5044",
        "location_id": null,
        ... (truncated for clarity)
      }
    ],
    "previous": {
      "first_name": "John",
      "updated_at": "2012-09-03T09:08:53.337-07:00"
    }
  },
  "webhook_id": 1,
  "business_id": 1
}

The indicated topic fields within data is similar to the json that Core API would return for the endpoint corresponding to the person.created topic. If you need other fields on the resource, you would make your own api call to the resource's corresponding Core API endpoint.

Requirements

The target url specified when creating a webhook must be be https.
Servers must respond with a 200 (Success) status code upon receiving a notification within 10 seconds.
Opening a connection to servers will timeout if it takes longer than 10 seconds.
If a target url server responds with a 410 (Gone) status code the webhook will be deleted.

Notification Lifetime

Generally, a notification will reach target servers within minutes and likely sooner. In the event that notification destinations are unavailable when POSTing, the notification will be retried based on the response status code returned. However, notifications may expire if the target server does not respond with a 200 after 20 retries.

Retry Status Codes
429
500-599

All other status codes returned by servers will result in the dropping the notification immediately. To help with debugging, use the trigger sample notification endpoint to receive a notification.

Retry Intervals

Retries are done with jittered exponential backoff. We will retry sending a notification 20 times over the next 4 days.

Automated Unsubscription

By default a webhook will continue to receive notifications indefinitely. However, when the user who created the webhook is no longer an owner of the business or the user has been removed from the business, all of their webhooks are unsubscribed automatically. Additionally, when the business has chosen to disable the webhooks feature, all of its webhooks will be unsubscribed automatically.

Debugging Notifications

Trigger sample notification.

POST /api/v3/webhooks/:webhook_id/trigger_sample_notification

Sends a sample notification to a webhook's target URL. Does not make a real data change.

Show curl example

REQUEST
$ curl -X POST https://mybiz.pike13.com/api/v3/webhook/1/trigger_sample_notification \
  -H "Authorization: Bearer XXXXXXXXXXXXXXX"
RESPONSE
HTTP/1.1 202 Accepted

Are you sure?

Webhooks API Documentation BETA

Get Started

API Description

Subscribing

Receiving

Example Flow

SUBSCRIPTION REQUEST

SUBSCRIPTION RESPONSE

NOTIFICATION PAYLOAD

Event occurrence

Desk

Resource Attributes

event_occurrence.upcoming

Payload Example

event_occurrence.created

Payload Example

event_occurrence.updated

Payload Example

event_occurrence.staff_member_updated

Payload Example

Invoice

Desk

Resource Attributes

A Special Note about Invoice Topics

invoice.new

Payload Example

invoice.created

Payload Example

invoice.updated

Payload Example

Person

Desk

Resource Attributes

person.created

Payload Example

person.updated

Payload Example

Person.deleted

Payload Example

Person Plan

Resource Attributes

person_plan.created

Payload Example

person_plan.updated

Payload Example

Plan

Resource Attributes

plan.updated

Payload Example

plan.ended

Payload Example

Plan Hold

Resource Attributes

plan_hold.created

Payload Example

plan_hold.updated

Payload Example

plan_hold.deleted

Payload Example

Punchcard

Resource Attributes

punchcard.started

Payload Example

punchcard.updated

punchcard.updated

Payload Example

punchcard.deleted

Payload Example

Transaction

Resource Attributes

transaction.created

Payload Example

transaction.updated

Payload Example

Visit

Desk

Resource Attributes

A Special Note about Visit Topics

visit.new