日本語

Kinchaku (1.4.0)

Download OpenAPI specification:

Kinchaku API v1

Kinchaku REST API endpoints are organized by resource type. You'll need to use different endpoints depending on your app's requirements.

1. Contacts

The contact resource stores information about the customers or pass bearers, including their contact details, stat metrics, and their consent status for receiving email marketing.

2. Projects

The project resource stores information about the pass projects, including the project type, the number of passes issued, and the number of visitors.

Supported Project types

  • Admission Ticket
  • Boarding Pass
  • Booking Pass
  • Coupon
  • Membership Pass
  • Store Punch Card
  • Subscription Pass
  • Voucher

3. Passes

The pass resource stores information about the passes, including the pass type and the pass status.


Limits

The API has a rate limit of 1000 requests per minute. Monitor x-ratelimit-limit and x-ratelimit-remaining headers.

429 error will be returned on duplicate requests (same request within 2 seconds).

Limitations

The Kinchaku API doesn't support bulk updates. You can work on only one object per request.

Contacts

Create contact

Creates a new contact record.

Authorizations:
Bearer
Request Body schema: application/json

Post the necessary fields for the API to create a new contact.

accepts_marketing
boolean
Default: false

Indicates if a contact has agreed to receive marketing communications.

birthday
string or null <date> non-empty

Date of birth of a person.

department
string or null [ 1 .. 255 ] characters

Department within the organization a person belongs to.

email
string or null <email> (Email) non-empty

Email address linked to the contact.

external_id
string or null non-empty

ID registered in an external system.

first_name
string or null non-empty

First name of a person.

gender
string or null non-empty

Gender identity of a person.

language
string non-empty

Preferred language of a contact.

last_name
string or null non-empty

Last name of a person.

meta
object or null

Additional information about the contact.

name
string or null non-empty

Full name of a person.

name_katakana
string or null non-empty

Full name of a person in Katakana.

phone
string or null [ 1 .. 255 ] characters

Phone number linked to the contact.

tags
Array of strings or null

Tags associated with the contact.

website
string or null

URL of the contact's website.

Responses

Request samples

Content type
application/json
Example
{
  • "first_name": "Rebecca"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all contacts

Retrieves a list of contacts.

Authorizations:
Bearer
query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get contact by ID

Retrieves the information of the contact with the matching ID.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update contact

Updates the existing contact record.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json

Patch the necessary fields to update a contact.

accepts_marketing
boolean
Default: false

Indicates if a contact has agreed to receive marketing communications.

birthday
string or null <date> non-empty

Date of birth of a person.

department
string or null [ 1 .. 255 ] characters

Department within the organization a person belongs to.

email
string or null <email> (Email) non-empty

Email address linked to the contact.

external_id
string or null non-empty

ID registered in an external system.

first_name
string or null non-empty

First name of a person.

gender
string or null non-empty

Gender identity of a person.

language
string non-empty

Preferred language of a contact.

last_name
string or null non-empty

Last name of a person.

meta
object or null

Additional information about the contact.

name
string or null non-empty

Full name of a person.

name_katakana
string or null non-empty

Full name of a person in Katakana.

phone
string or null [ 1 .. 255 ] characters

Phone number linked to the contact.

tags
Array of strings or null

Tags associated with the contact.

website
string or null

URL of the contact's website.

Responses

Request samples

Content type
application/json
Example
{
  • "first_name": "Rebecca"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete contact

Deletes a contact record.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthenticated."
}

Get contact by External ID

Retrieves the information of the contact with the matching External ID.

Authorizations:
Bearer
path Parameters
external_id
required
string

ID registered in an external system.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete contact by External ID

Deletes a contact record.

Authorizations:
Bearer
path Parameters
external_id
required
string

ID registered in an external system.

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthenticated."
}

Get contact passes

Get a list of passes by contact's ID.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

is_expired
boolean

Filter by pass expiration status.

is_used
boolean

Filter by pass usage status.

is_voided
boolean

Filter by pass void status

venue
string <uuid>

Venue in which the pass was issued or used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get contact passes by external ID

Get a list of passes by contact's External ID.

Authorizations:
Bearer
path Parameters
external_id
required
string

ID registered in an external system.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

is_expired
boolean

Filter by pass expiration status.

is_used
boolean

Filter by pass usage status.

is_voided
boolean

Filter by pass void status

venue
string <uuid>

Venue in which the pass was issued or used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get pass activity by contact ID

Get pass activity records for the given contact ID.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
operation
string
Enum: "punch" "redeem" "checkin" "reward"

Filters activity by operation. punch for stamp card additions/removals; redeem for stamp cards, point cards, vouchers, etc.; checkin for tickets, membership or subscription passes; reward for points/stamps awarded or spent against a configured reward. Records with operation bonus (one-off bonus point awards, e.g. enrollment or campaign) are returned but cannot be filtered on.

valid
boolean

Filters out expired activity events. Used for loyalty point cards with expiring points.

with_deleted
boolean

Includes deleted activity records in the response.

start_date
string <date>

Show activity from project's start date.

end_date
string <date>

Show activity up to project's end date.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get project contacts

Retrieves a list of customer data associated with a project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Messages

Passes

Get all passes

Get a list of passes

Authorizations:
Bearer
query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

is_expired
boolean

Filter by pass expiration status.

is_used
boolean

Filter by pass usage status.

is_voided
boolean

Filter by pass void status

venue
string <uuid>

Venue in which the pass was issued or used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get pass by ID

This operation retrieves a specific pass using its ID.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
with_qr
string
Enum: "base64" "link"

Include QR code in response. Can be used for pass scan.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Void pass

Voids a pass.

This operation is used to invalidate a pass.
It requires the unique identifier (ID) of the pass to perform this operation.

Note: The action is irreversible and the pass cannot be reactivated.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthenticated."
}

Update pass

Updates the existing pass record.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json

Update Pass request body.

aux_field
string <= 30 characters

A field on the front of a wallet pass for displaying additional information.

object

Booking information for the pass.

expires_at
null or string <date-time>

Date and time (in ISO 8601 format) when the pass expires.

external_id
null or string

ID registered in an external system.

smartlock_pin
integer

A PIN number for a smart lock.

smartlock_qr
string

A QR code with an embedded PIN code of a smart lock.

tier
null or integer

Can be used to manually change pass tier

voided
null or boolean

(Optional) Provide to change pass status.

Responses

Request samples

Content type
application/json
{
  • "aux_field": "string",
  • "booking": {
    },
  • "expires_at": null,
  • "external_id": null,
  • "smartlock_pin": 0,
  • "smartlock_qr": "string",
  • "tier": null,
  • "voided": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get pass activity

This operation retrieves the activity records for a specific pass.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
operation
string
Enum: "checkin" "punch" "redeem" "reward"

Filters activity by operation. punch for stamp card additions/removals; redeem for stamp cards, point cards, vouchers, etc.; checkin for tickets, membership or subscription passes; reward for points/stamps awarded or spent against a configured reward. Records with operation bonus (one-off bonus point awards, e.g. enrollment or campaign) are returned but cannot be filtered on.

valid
boolean

Filters out expired activity events. Used for loyalty point cards with expiring points.

with_deleted
boolean

Includes deleted activity records in the response.

start_date
string <date>

Show activity from project's start date.

end_date
string <date>

Show activity up to project's end date.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get point history

This operation initiates a request to retrieve loyalty point activity logs associated with a pass.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
from
string <date>

Show points history from date. Will be cast to start of the day.

to
string <date>

Show points history up to date. Will be cast to end of the day.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Punch pass

Adds a stamp to a stamp card pass.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json
redeem
Array of strings or null

Rewards to redeem.

value
integer

Stamps or points count.

venue
null or string <uuid> (UUID)

A venue uuid where the punch activity was performed.

Responses

Request samples

Content type
application/json
{
  • "redeem": [
    ],
  • "value": 0,
  • "venue": null
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Redeem pass

Redeems a voucher or a coupon value or a reward (in loyalty programs).

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json
aux_field
string or null

A field on the front of a wallet pass for displaying additional information.

redeem
Array of strings or null

Rewards to redeem

rewards
Array of null or strings or null <uuid> (UUID) [ items <uuid > ]

Array of loyalty program reward IDs to redeem.

venue
null or string <uuid> (UUID)

The short ID of the venue where the pass was redeemed.

Responses

Request samples

Content type
application/json
{
  • "aux_field": "string",
  • "redeem": [
    ],
  • "rewards": [
    ],
  • "venue": null
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Update pass value

Update point card value.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json
description
string or null <= 255 characters

This field allows for the inclusion of optional descriptions to accompany updates made to points within the system.

pay_sum
integer or null

The amount paid by the customer to receive points.

value
integer

Number of loyalty points.

venue
null or string <uuid> (UUID)

A venue uuid where the point activity was performed.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "pay_sum": 0,
  • "value": 0,
  • "venue": null
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Change pass's `value_total`

Updates the total value of the point card (cumulative points). This can be used for loyalty program passes to force an upgrade to a new tier.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json
description
string or null <= 255 characters

This field allows for the inclusion of optional descriptions to accompany updates made to points within the system.

pay_sum
integer or null

The amount paid by the customer to receive points.

value
integer

Number of loyalty points.

venue
null or string <uuid> (UUID)

A venue uuid where the point activity was performed.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "pay_sum": 0,
  • "value": 0,
  • "venue": null
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Check-in pass

This operation initiates a request to check in a pass.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json
aux_field
string or null

A field on the front of a wallet pass for displaying additional information.

venue
null or string <uuid> (UUID)

A venue uuid where the check-in activity was performed.

Responses

Request samples

Content type
application/json
{
  • "aux_field": "string",
  • "venue": null
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Check-out pass

This operation initiates a request to check out a pass.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Undo pass activity

Undo Pass activity operation.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

activity_id
required
integer

ID of the activity record.

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Get project passes

Get a list of passes associated with the project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

start_date
string <date>

Start date of a pass project.

end_date
string <date>

End date of a pass project.

is_expired
boolean

Filter by pass expiration status.

is_used
boolean

Filter by pass usage status.

is_voided
boolean

Filter by pass void status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Issue pass

Issue a pass associated with the project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
with_qr
string
Enum: "base64" "link"

Include pass QR code in the response.

Request Body schema: application/json

Issue Pass request body.

aux_field
string <= 30 characters

A field on the front of a wallet pass for displaying additional information.

object

Booking information for the pass.

object (Contact)

Customer or Pass Bearer data resource.

The resource includes personal information, contact details, and social media accounts.

Fields without a value are left out of the response, not returned as null.

expires_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the pass expires.

external_id
null or string

ID registered in an external system.

fare_id
string <uuid>

A uuid of the fare. Used in transport passes.

plan_id
null or string <uuid> (UUID)

A uuid of the pricing plan.

send
boolean

Send an email with pass link to the contact.

smartlock_pin
integer

A PIN number for a smart lock.

smartlock_qr
string

A QR code with an embedded PIN code of a smart lock.

value
integer
venue
null or string <uuid> (UUID)

A venue uuid where the pass was issued.

Responses

Request samples

Content type
application/json
{
  • "aux_field": "string",
  • "booking": {
    },
  • "contact": {
    },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "external_id": null,
  • "fare_id": "1ed58791-3cac-4030-9cf0-4f9e1c25fc4b",
  • "plan_id": null,
  • "send": true,
  • "smartlock_pin": 0,
  • "smartlock_qr": "string",
  • "value": 0,
  • "venue": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get pass messages

Retrieves all the messages associated with a specific wallet pass.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create pass message

Creates a new wallet pass message.

Messages can include notifications, updates, or any other type of communication related to the pass. The message can be sent immediately, scheduled for a specific date and time, or saved as a draft.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json

Send immediately, schedule or save draft message.

body
required
string [ 2 .. 80 ] characters
body_en
string or null [ 2 .. 80 ] characters
scheduled_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

is_draft
boolean

Responses

Request samples

Content type
application/json
{
  • "body": "Hello",
  • "scheduled_at": "2030-01-20T12:00:00+09:00",
  • "is_draft": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete pass message

Deletes a scheduled message from the queue before it is sent.

It targets messages that have been scheduled for future delivery, allowing users or systems to cancel the sending of these messages if circumstances change or if the message is no longer needed. This operation requires the unique identifier (ID) of the scheduled message to accurately locate and delete it from the scheduling system. Once a message is deleted, it cannot be recovered, and any actions intended by the message will not be executed.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

message_id
required
string

ID of the message.

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthenticated."
}

Update pass message

This operation allows for the modification of an existing message's content or metadata. It is designed to accommodate changes or corrections to messages that have already been created but not yet sent.

To perform an update, the unique identifier (ID) of the message must be provided. The system then applies the requested changes to the message, ensuring it reflects the most current information before it reaches its intended recipients.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

message_id
required
string

ID of the message.

Request Body schema: application/json
body
required
string [ 2 .. 80 ] characters
body_en
string or null [ 2 .. 80 ] characters
scheduled_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

is_draft
boolean

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "body_en": "string",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "is_draft": true
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Projects

Get pass activity by project ID

Get activity records for passes issued in the given project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
operation
string
Enum: "punch" "redeem" "checkin" "reward"

Filter by operation

valid
boolean

Filters out expired activity events. Used for loyalty point cards with expiring points.

with_deleted
boolean

Includes deleted activity records in the response.

start_date
string <date>

Project's start date.

end_date
string <date>

Project's end date.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get projects

This operation retrieves a list of all projects currently managed within the system.

Authorizations:
Bearer
query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

tags
Array of strings

Tag names used to filter projects. Defaults By default, it returns projects with ANY of the provided tags.

filter_logic
string
Default: "OR"
Enum: "OR" "AND"
Example: filter_logic=AND

Specifies the logical operator to be used when applying multiple filters.

venue
string <uuid>

Venue in which the pass was issued or used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get project

Get Project information.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get pass activity

Get Wallet Pass activity by Project type. Supported types:

  • coupon
  • voucher
  • ticket
  • member
  • stamp
  • transport
  • subscription
Authorizations:
Bearer
path Parameters
type
required
string

Type of the project.

query Parameters
start_date
string <date>

Show activity from project's start date.

end_date
string <date>

Show activity up to project's end date.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get project contacts

Retrieves a list of customer data associated with a project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get project passes

Get a list of passes associated with the project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

start_date
string <date>

Start date of a pass project.

end_date
string <date>

End date of a pass project.

is_expired
boolean

Filter by pass expiration status.

is_used
boolean

Filter by pass usage status.

is_voided
boolean

Filter by pass void status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Issue pass

Issue a pass associated with the project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
with_qr
string
Enum: "base64" "link"

Include pass QR code in the response.

Request Body schema: application/json

Issue Pass request body.

aux_field
string <= 30 characters

A field on the front of a wallet pass for displaying additional information.

object

Booking information for the pass.

object (Contact)

Customer or Pass Bearer data resource.

The resource includes personal information, contact details, and social media accounts.

Fields without a value are left out of the response, not returned as null.

expires_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the pass expires.

external_id
null or string

ID registered in an external system.

fare_id
string <uuid>

A uuid of the fare. Used in transport passes.

plan_id
null or string <uuid> (UUID)

A uuid of the pricing plan.

send
boolean

Send an email with pass link to the contact.

smartlock_pin
integer

A PIN number for a smart lock.

smartlock_qr
string

A QR code with an embedded PIN code of a smart lock.

value
integer
venue
null or string <uuid> (UUID)

A venue uuid where the pass was issued.

Responses

Request samples

Content type
application/json
{
  • "aux_field": "string",
  • "booking": {
    },
  • "contact": {
    },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "external_id": null,
  • "fare_id": "1ed58791-3cac-4030-9cf0-4f9e1c25fc4b",
  • "plan_id": null,
  • "send": true,
  • "smartlock_pin": 0,
  • "smartlock_qr": "string",
  • "value": 0,
  • "venue": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get project messages

Retrieves a list of messages for passes issued in the given project.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

query Parameters
limit
integer <= 100
Default: 15

Record limit.

page
integer
Default: 1

Page number.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a pass message

Create a new pass message.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

Request Body schema: application/json

Send immediately, schedule or save draft message.

body
required
string [ 2 .. 80 ] characters
body_en
string or null [ 2 .. 80 ] characters
scheduled_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

is_draft
boolean

Responses

Request samples

Content type
application/json
{
  • "body": "Hello",
  • "scheduled_at": "2030-01-20T12:00:00+09:00",
  • "is_draft": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete pass message

Delete a scheduled pass message.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

message_id
required
string

ID of the message.

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthenticated."
}

Update pass message

This endpoint is used to update a message for a wallet pass. It allows you to modify the content, schedule, and draft status of the message. The request body should include the updated message details, such as the body text, scheduled date, and draft status.

Note: The body text should be between 2 and 80 characters long.

Authorizations:
Bearer
path Parameters
id
required
string

System generated ID.

message_id
required
string

ID of the message.

Request Body schema: application/json
body
required
string [ 2 .. 80 ] characters
body_en
string or null [ 2 .. 80 ] characters
scheduled_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

is_draft
boolean

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "body_en": "string",
  • "scheduled_at": "2019-08-24T14:15:22Z",
  • "is_draft": true
}

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Schemas

Activity

id
number
wallet_pass_id
string <uuid>

ID of the pass.

project_id
string <uuid>

Only on GET /projects/activity/{type}.

project_title
string

Name of the project. Only on GET /projects/activity/{type}.

object (CompactContact)

The contact that holds the pass, in short form. Fields without a value are omitted, as in Contact.

operator_id
string <uuid>
object
Venue (object) or null
operation
string

What happened: punch, checkin, use, reward, redeem or bonus.

value
number
used
number
description
null or string
amount
integer or null

Amount of money used for point exchange.

redeemed_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

expires_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

created_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

updated_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

deleted_at
string or null <date-time> (DateTime)

When the record was deleted. Only on deleted records, which with_deleted returns.

{
  • "id": 0,
  • "wallet_pass_id": "655f900e-3575-419e-b898-da2b2a74f1ad",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "project_title": "string",
  • "contact": {
    },
  • "operator_id": "fa9de6bb-1df8-4ba6-9e6d-1172fbf7e166",
  • "operator": {
    },
  • "venue": {
    },
  • "operation": "string",
  • "value": 0,
  • "used": 0,
  • "description": null,
  • "amount": 0,
  • "redeemed_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

Address

id
string <uuid>

System generated ID.

role
string non-empty
Default: "main"

An address category (home, office etc.)

street
string or null
other
string or null
city
string or null
state
string or null
country
string or null
postcode
string or null
phone
string or null
created_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

updated_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

{
  • "role": "main",
  • "street": "博多駅東",
  • "other": null,
  • "city": "福岡市博多区",
  • "state": "福岡県",
  • "country": "JP",
  • "postcode": "8120013"
}

Contact

Array of objects (Address) unique

List of addresses linked to a person.

tags
Array of strings

Tags associated with the contact.

contact_image
string or null <uri> (URL) non-empty

URL of a photo image.

is_company
boolean

Whether the contact is a company.

last_contact_at
string or null <date-time> (DateTime)

When one of the contact's passes last recorded an activity (check-in, punch, redemption and so on).

object (Venue)

Venue of the most recent visit. Returned together with visited_venues.

created_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

email
string or null <email> (Email) non-empty

Email address linked to a person.

phone
string

Phone number linked to the contact.

external_id
string or null

External ID of the contact.

shortuuid
string

Short identifier of the contact, used in pass and page links.

first_name
string or null

First name of a person.

id
string <uuid>

system generated ID.

last_name
string or null

Last (family) name of a person.

object

Additional information about a person.

name
string or null

Full name of a person.

name_katakana
string or null

Name of a person in Katakana.

birthday
string <date>

Date of birth. Legacy name: the same value as birthdate.

birthdate
string <date>

Date of birth of a person.

updated_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

visited_venues
Array of objects or null

List of venues or facilities where a person has used their passes.

{
  • "id": "94a6e034-f3b2-4164-9e0a-a28114d9474b",
  • "external_id": "e8a01cfbea59",
  • "email": "taro@kinchaku.com",
  • "name": "タロウ ヨウロウ",
  • "first_name": "ヨウロウ",
  • "last_name": "タロウ",
  • "name_katakana": "ヨウロウタロウ",
  • "visited_venues": [ ],
  • "addresses": [
    ],
  • "meta": {
    },
  • "created_at": "2021-10-17T04:21:10.000000Z",
  • "updated_at": "2021-10-17T04:21:22.000000Z"
}

CompactContact

id
string <uuid>

system generated ID.

external_id
string or null

External ID of the contact.

shortuuid
string

Short identifier of the contact, used in pass and page links.

email
string or null <email> non-empty

Email address linked to a person.

phone
string

Phone number linked to the contact.

name
string or null

Full name of a person.

first_name
string or null

First name of a person.

last_name
string or null

Last (family) name of a person.

name_katakana
string or null

Name of a person in Katakana.

contact_image
string or null <uri> non-empty

URL of a photo image.

is_company
boolean

Whether the contact is a company.

birthday
string <date>

Date of birth. Legacy name: the same value as birthdate.

object

Additional information about a person.

created_at
string or null <date-time>

Date and time in ISO 8601 format.

updated_at
string or null <date-time>

Date and time in ISO 8601 format.

deleted_at
string or null <date-time> (DateTime)

When the contact was deleted; null otherwise.

last_visit_at
string or null <date-time> (DateTime)

When the contact last visited.

{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "external_id": "string",
  • "shortuuid": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "name_katakana": "string",
  • "contact_image": "http://example.com",
  • "is_company": true,
  • "birthday": "2019-08-24",
  • "meta": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "last_visit_at": "2019-08-24T14:15:22Z"
}

DateTime

string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

"2019-08-24T14:15:22Z"

Email

string or null <email> (Email) non-empty

Email address.

"user@example.com"

Error

required
object
{
  • "errors": {
    }
}

Message

android_count
integer >= 0

Number of Android devices that have pass installed. Note: Messages for Apple Wallet and Google Wallet passes have different behavior.

body
string non-empty

A text of the pass message in Japanese.

body_en
string non-empty

A text of the pass message in English. (will be displayed on the devices with non-Japanese language settings)

created_at
string or null <date-time> (DateTime)

Date and time in ISO 8601 format.

header
null or string

A title of the pass message (android only)

id
string <uuid>

System generated ID.

ios_count
integer >= 0

Number of iOS devices that have pass installed. Note: Messages for Apple Wallet and Google Wallet passes have different behavior.

boolean or integer

Indicates if the message is a draft. Returned as a boolean or as 0/1.

object

A user who triggers the send action.

operator_id
string <uuid>

ID of the user who sent or scheduled the message.

scheduled_at
string or null <date-time> (DateTime)

Date and time when the message is scheduled to be sent.

sent_at
string or null <date-time> (DateTime)

The actual date and time when the message was sent.

updated_at
string or null <date-time> (DateTime)

Date and time when the record was last updated.

{
  • "id": "95584608-4291-4565-a5a6-ac32c443abf9",
  • "operator_id": "8ddb7a06-0a8f-46bd-a27e-d37adf4dc138",
  • "header": null,
  • "body": "hello",
  • "is_draft": 0,
  • "android_count": 0,
  • "ios_count": 0,
  • "sent_at": "2022-01-13T08:47:26.000000Z",
  • "scheduled_at": null,
  • "created_at": "2022-01-13T08:47:26.000000Z",
  • "updated_at": "2022-01-13T08:47:26.000000Z",
  • "operator": {
    }
}

Pagination

current_page
integer <int32>
Default: 1
from
integer <int32> >= 1
Default: 1
last_page
integer <int32>
per_page
integer <int32>
Default: 15
to
integer <int32>
total
integer <int32>
{
  • "current_page": 1,
  • "from": 1,
  • "last_page": 8,
  • "per_page": 15,
  • "to": 15,
  • "total": 115
}

Project

amount_off
integer or null

Discount amount, in currency. Coupon projects only.

archived_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was archived.

object

Barcode settings displayed on the pass issued in the given project.

booking_units
Array of any or null

Booking units represent a person, service, or resource that can be booked.

Array of objects

Venues included in a bundle, with how many times each can be redeemed. Bundle projects only.

contact_address
string or null

Support email address available to customers

cancelation
string or null

Cancellation policy for the project written in Japanese.

cancelation_en
string or null

Cancellation policy for the project written in English.

created_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was created.

currency
string

Currency of amount_off, such as JPY. Coupon projects only.

description
string

Description of the project written in Japanese (Visible to your customers).

description_en
string or null

Description of the project written in English (Visible to your customers).

discount_terms
string

The discount as display text, such as 10% off. voucher coupons return their voucher text, and monetary coupons an empty string. Coupon projects only.

discount_type
string or null

Kind of discount: fixed, percent, voucher or monetary. Coupon projects only.

end_time
string

End time (HH:MM). Omitted when not set.

object

Expiration setting for the passes issued in the given project.

expire_points_end
integer or null

Points expire at the end of the month this many months after they are earned. Used when expire_points_in is not set. Loyalty projects only.

expire_points_in
integer or null

Points expire this many days after they are earned; null when not set. Loyalty projects only.

external_id
string or null

External ID of the project.

has_activity
integer

Indicates whether the passes issued in the given project have any activity.

has_data_collection
boolean

Indicates if the project collects personal data from the customers.

has_registration
boolean

Indicates if customer account registration feature is enabled in the given project.

hour_price
integer

Price set for one hour; 0 when not set. Loyalty projects only.

id
string <uuid>

System generated ID of a pass project.

object
is_published
boolean
Default: false

Indicates if the project is published and the pass distribution page is visible to the customers.

object or array <= 0 items

Limit on the stamps a pass can get per period, such as {"period": "day", "count": 1}. An empty array ([]) when there is no limit. Loyalty projects only.

link
string

Link to the distribution page.

link_to_privacy
string or null <uri> (URL) non-empty

A URL to the privacy policy of the project.

max_redemptions
integer or null

Maximum number of redemptions allowed for the passes issued in the given project.

name
string

Name of the project written in Japanese.

name_en
string or null

Name of the project written in English.

order_limit
integer or null

Maximum number of passes that can be obtained in one purchase.

object

The visual settings for the passes issued in the given project.

percent_off
number

Discount percentage; 0 when not set. Coupon projects only.

Array of objects (Plan)
point_price
integer

Price set for one point; 0 when not set. Loyalty projects only.

points_per_tier
integer or null

Points a member needs to reach the next member tier; null when tiers are not used. Loyalty projects only.

privacy
string or null

Privacy policy text of the project written in Japanese.

privacy_en
string or null

Privacy policy text of the project written in English.

published_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the project was published.

quantity
integer or null

Maximum number of passes the coupon can issue; null means no limit. Coupon projects only.

redemption_price
integer or null

Price of the one redemption.

Array of objects

Rewards of the base tier, sorted by stamps_required. Returned by GET /projects/{id}. Loyalty projects only.

stamp_price
integer

Price set for one stamp; 0 when not set. Loyalty projects only.

start_date
string or null <date-time>

The start date of the project.

start_time
string

Start time (HH:MM). Omitted when not set.

object
subtype
any
Enum: "admission" "basic" "bundle" "commuter" "event" "fixed" "hotel_pass" "kaisuken" "lift" "meeting_pass" "member" "monetary" "multiride" "percent" "stamp" "voucher"
Array of objects (Tag)
object
total_stamps
integer

Stamps that fill the stamp card; 0 when not set. Loyalty projects only.

transport_type
string
Enum: "PKTransitTypeAir" "PKTransitTypeBoat" "PKTransitTypeBus" "PKTransitTypeGeneric" "PKTransitTypeTrain"

Apple Wallet transit type of the pass. Transport projects only.

type
any
Enum: "booking" "coupon" "loyalty" "service" "ticket" "transport"
updated_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was last updated.

Array of objects (Venue)

List of venues or facilities where the passes issued from the given project can be used.

object or null
voucher
string or null

Voucher text of a voucher coupon. Coupon projects only.

{
  • "id": "9ab9f0d3-41f6-43b9-97f7-d875e7a64e50",
  • "external_id": null,
  • "name": "New hotel pass",
  • "name_en": null,
  • "type": "booking",
  • "subtype": "hotel_pass",
  • "link": "/booking/9ab9f0d3-41f6-43b9-97f7-d875e7a64e50",
  • "start_date": null,
  • "is_published": true,
  • "published_at": "2023-11-29T05:06:10.000000Z",
  • "archived_at": null,
  • "created_at": "2023-11-29T05:00:00.000000Z",
  • "updated_at": "2024-05-31T06:13:27.000000Z",
  • "contact_address": null,
  • "booking_units": [
    ],
  • "venues": [
    ],
  • "description": "Some description",
  • "description_en": null,
  • "terms": {
    },
  • "privacy": "sss",
  • "privacy_en": null,
  • "cancelation": null,
  • "cancelation_en": null,
  • "link_to_privacy": null,
  • "images": {},
  • "barcode": {
    },
  • "has_registration": true,
  • "has_data_collection": false,
  • "redemption_price": 0,
  • "pass_settings": {
    },
  • "order_limit": null,
  • "expiration": {
    },
  • "max_redemptions": null,
  • "has_activity": 0,
  • "tags": [
    ],
  • "stats": {
    },
  • "plans": [
    ],
  • "sales_settings": {
    }
}

Plan

archived_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was archived.

checkin_open
string

How long before the start time check-in opens, as a duration such as 1 hour. Empty when not set: check-in then opens 15 minutes before a reservation, or 1 hour before the start otherwise.

object or array <= 0 items

Colour overrides for passes of this plan. An empty array ([]) when none are set.

created_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was created.

description
string or null

Description of the pricing plan written in Japanese.

description_en
string or null

Description of the pricing plan written in English.

disable_cancel
boolean

Indicates if cancellations are disabled for the plan.

disable_refund
boolean

Indicates if refunds are disabled for the plan.

object
id
string <uuid>

System generated ID of a pricing plan.

object
interval
string

This parameter defines the interval at which billing occurs for subscription passes. Valid options are: day, week, month, or year.

interval_count
integer

The number of intervals between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. Used for subscription passes.

link
string

URL of the distribution page for the plan.

max_redemptions
integer

Maximum number of redemptions allowed for the passes purchased for the plan.

name
string

Name of the pricing plan written in Japanese.

name_en
string or null

Name of the pricing plan written in English.

pass_layout
string

Layout of the wallet pass, for example branded_strip_image (the default), no_image, client_picture_and_name or aux_in_primary.

price
integer

Price of the plan.

price_without_tax
integer

Price of the plan without tax.

quantity
integer or null

The maximum number of passes to be sold for the plan.

tax_amount
integer

Tax amount of the plan.

tax_included
boolean

Indicates if the price includes tax.

trial_days
integer or null

Number of days for a trial period. Used for subscription passes.

updated_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was last updated.

sales_start
string or null <date-time>

Date and time (in ISO 8601 format) when the sales start.

sales_end
string or null <date-time>

Date and time (in ISO 8601 format) when the sales end.

{
  • "id": "9b8b64b9-d761-4d1d-ae96-fba25bef64c9",
  • "name": "Category 1",
  • "name_en": null,
  • "link": "/booking/9ab9f0d3-41f6-43b9-97f7-d875e7a64e50/categories/fba25bef64c9",
  • "interval": "once",
  • "quantity": null,
  • "max_redemptions": 1,
  • "interval_count": 1,
  • "trial_days": 0,
  • "tax_included": true,
  • "description": "",
  • "description_en": "",
  • "archived_at": null,
  • "created_at": "2024-03-12T07:52:06.000000Z",
  • "updated_at": "2024-04-04T02:17:18.000000Z",
  • "price": 1000,
  • "price_without_tax": 909,
  • "tax_amount": 91,
  • "disable_refund": false,
  • "disable_cancel": false,
  • "images": {},
  • "expiration": {
    },
  • "sales_end": "2024-06-26T14:59:00.000000Z",
  • "sales_start": "2024-06-24T15:00:00.000000Z"
}

Tag

name
string

Name of the tag stored in Kinchaku system.

key
string

The key part of a tag.

value
string

The value part of a tag.

{
  • "name": "genre:rock",
  • "key": "genre",
  • "value": "Rock"
}

Venue

id
string <uuid>

System generated ID.

title
string

Title of the venue or facility.

tenant_code
string

A unique code assigned by the facility

total
integer

How many times the contact visited the venue. Only in a contact's visited_venues.

address_string
string or null

A text representation of the address, visible to the users.

object (Address)
{
  • "id": "92070da8-fcd2-4623-bf2b-5d182d8bfb65",
  • "title": "Tower venue",
  • "tenant_code": "tcode1",
  • "address": {
    },
  • "address_string": "Fukuoka Tower"
}

WalletPass

canceled_at
string or null <date-time> (DateTime)

When the pass was voided. null while the pass is active.

checkedin_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the pass was checked in.

checkins_count
integer

Number of times the pass was checked in.

object (Contact)

Contact information of the pass owner.

contact_id
null or string <uuid> (UUID)

ID of the pass owner contact. Could be null for anonymous passes.

created_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was created.

is_valid
boolean

Indicates if the pass can be used now: not used, not expired, not voided, and past its activation date.

serial_number
string

Sequential pass number: the project's prefix and a zero-padded number. Omitted when the project does not number its passes.

webpass_link
string or null <uri> (URL) non-empty

Webpass link.

download_link
string or null <uri> (URL) non-empty

Pass download link.

expires_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the pass expires.

external_id
string or null

ID registered in an external system.

has_android
boolean
Default: false

If pass is installed on an android device.

has_ios
boolean
Default: false

If pass is installed on an iOS device.

id
string <uuid>

System generated ID.

installed_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the pass was installed into a wallet app.

is_expired
boolean
Default: false

Indicates if the pass has expired.

is_used
boolean
Default: false

Indicates if the pass has been used.

is_voided
boolean
Default: false

Indicates if the pass has been voided.

points_balance
number or null

Available when a point system was enabled in the pass project. Shows the current balance of loyalty points.

project_id
string <uuid>

ID of a project the pass belongs to.

plan_id
string or null

ID of a plan the pass belongs to.

Plan (object) or null
qrcode
string or null

Available when the with_qr query parameter is set to base64.

qrcode_link
string or null <uri> (URL) non-empty

Available when the with_qr query parameter is set to link.

redeemed_count
integer or null

Number of value redemptions used.

redemptions_left
integer or null

Number of value redemptions left.

Array of objects

Loyalty program rewards associated with the pass.

shortuuid
string

A short unique identifier of the pass.

smartlock_pin
string or null

A PIN number for a smart lock.

smartlock_qr
string or null

A QR code with an embedded PIN code of a smart lock. Can be used in qrcode shown on the pass.

start_date
null or string <date-time>

Date and time (in ISO 8601 format) when the event or service starts.

status
string
tier
null or integer >= 0

Tier of a loyalty program.

uninstalled_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the pass was uninstalled from a wallet app.

unlocked_count
null or integer

Number of unlocked rewards.

updated_at
string or null <date-time> (DateTime)

Date and time (in ISO 8601 format) when the record was last updated.

value_sum
integer or null
value_tier
integer or null
value_total
integer or null
{
  • "checkedin_at": "2020-11-13T04:31:14.000000Z",
  • "checkins_count": 1,
  • "contact": {
    },
  • "contact_id": "9454865a-0891-48e7-ae59-f6a82f822be1",
  • "created_at": "2020-11-13T04:31:14.000000Z",
  • "expires_at": "2021-09-30T14:59:59.000000Z",
  • "has_android": false,
  • "has_ios": true,
  • "id": "91fef32b-17df-4843-864a-6935aead2029",
  • "installed_at": "2020-12-25T07:59:13.000000Z",
  • "is_expired": false,
  • "is_used": false,
  • "is_voided": false,
  • "project_id": "91fef16c-cb9c-43a2-883d-dc837ef7d0d8",
  • "plan_id": "9b8b64b9-d761-4d1d-ae96-fba25bef64c9",
  • "redeemed_count": 2,
  • "redemptions_left": 1,
  • "rewards": [
    ],
  • "shortuuid": "geKkkmk65o8KiJG28qEdyT",
  • "smartlock_pin": "78293",
  • "smartlock_qr": "424434",
  • "start_date": "2020-11-13T04:31:14.000000Z",
  • "status": "installed",
  • "tier": 2,
  • "uninstalled_at": "2020-11-13T04:31:14.000000Z",
  • "unlocked_count": 0,
  • "updated_at": "2021-03-09T02:57:50.000000Z",
  • "value_sum": 17,
  • "value_tier": 5,
  • "value_total": 17,
}

URL

string or null <uri> (URL) non-empty

URL.

UUID

null or string <uuid> (UUID)

A unique identifier assigned by the system, adhering to the UUID format.

null