Support Filmchief Developer Help Center Filmchief REST API

Welcome to the Filmchief Developer Help Center

API reference, tools and resources for developers

The Filmchief REST API documentation

Getting started

Audience

This documentation is designed for people familiar with REST API programming and object-oriented programming concepts. You should also be familiar with Filmchief from a user's point of view. There are many REST API tutorials available on the Web.

In Filmchief, we recommend acquiring a Web developer role (ask your Administrator about this) and enable Show API column names on your My account page. This way, you will be able to navigate through the festival database to get a sense of its contents, and see the internal column names which you will be using in your API calls.

Prerequisites

Before you start, make sure that you have everything you need.

  • A Premium Filmchief license is required.
  • The Filmchief API must be enabled.
  • The Primary API user must be defined.
  • The master API key
  • An HTML editor
  • A web server

About the Primary API user

The Primary API user is probably you: the person responsible for the API requests that are sent to our servers. If an API request fails, you will receive an error report that informs you about the details of what went wrong.

The Primary API user also serves as our primary contact for important notifications concerning the Filmchief API.

You can set the Primary API user at System About Filmchief.

Getting the master API key

To use the Filmchief REST API, you need the master API key. If your festival has a premium license, you will it at System About Filmchief

Connecting with the API

Before you can make any API calls, you need to connect with the API to obtain a token. To do this, include the following code in your project:

<?php $filmchiefApiConnection = json_decode( file_get_contents('https://«FESTIVAL IDENTIFIER».filmchief.com/api/php?key=' . password_hash('«MASTER API KEY»', PASSWORD_DEFAULT)), true ); ?>

This code requires PHP 5.5 or higher to work, because of the password_hash function. If you have version 5.4 or less, you can download a PHP library here.

import bcrypt import json connectUrl = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php?key=' + bcrypt.hashpw('«MASTER API KEY»', bcrypt.gensalt()) with open(connectUrl, 'r') as openFile: content = openFile.read() fileApiConnection = json.loads(content)

Note: Replace FESTIVAL IDENTIFIER with your festival’s subdomain name (the part before .filmchief.com) and MASTER API KEY with the key obtained from Filmchief.

Authentication

The filmchiefApiConnection object contains a token that you need to use in subsequent API calls. The token is valid for 5 minutes.

Reader module

A service for reading data from Filmchief.

Endpoint
To use any of the methods in the Reader module, call the following URL:
https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader
token
In each API call, you must specify the token obtained in the authorization call described above.
proc
The requested method.
+ method parameters
Include the parameters of the requested method in your API call.
Methods
checkEmailAvailability
Return Value:  None
Call this method to verify if an email address can be used to create a new account.
options
emailAddress Required
Type:  string
The email address to check.
validationType
Type:  string

Use this keyword to express for which purpose the email availability check is being made. Can be one of the following values:

new-email
(default) Verify the specified email address as though it were to be used to create a new account.
new-email-strict
Same as new-email, but no new account can be created if a user record exists without an account (statusName is noAccount, see below)
billing-email
For internal use only. (Not intended to be used in the Reader API)
lang
Type:  string
Localizes some of the returned values. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
result object: data
activationLinkSentTimeDiffSeconds
Type:  int
Indicates how long ago an email with an account activation link was sent to this email address. Note: this number is always negative.
allowCreateAccount
Type:  bool
Indicates if a new user account can be created using the specified email address.
statusName
Type:  string
This keyword indicates why a new user account can or cannot be created. The following values are possible:
nonexistent
No user record exists with the specified email address - a new account can be created.
deleted
The account has been deleted - a new account can be created.
blocked
The account has been blocked by the festival. The account must first be unblocked or deleted before the email address can be used again to sign in or create an account.
noAccount
A user record exists, but there is no account. The account can be claimed by requesting an activation token using the link in the statusDescriptionOwnerExternal property of the result data.
activationTokenExpired
Activation link of non-activated account expired - the user did not activate the account in time and must request a new activation token using the link in the statusDescriptionOwnerExternal property of the result data.
activationPending
Waiting for activation - an email with an activation link was sent activationLinkSentTimeDiffSeconds seconds ago (and it is still valid). The user should be instructed to find that email and click on the activation link.
active
The email address belongs to an active account. Access can be reclaimed by the "Forgot password" procedure.
statusText
Type:  string Localized
A human-readable version of the statusName value.
statusDescriptionAdmin
Type:  string (HTML) Localized

Recommended course of action based on the status of the account associated with the specified email address.

Note: This text is only intended for internal use by administrators.

For example:
This email address is already associated with a <a href="/admin/user/12345">profile without an account</a>. The account can be claimed by the owner of the email address.
statusDescriptionOwnerExternal
Type:  string (HTML) Localized

Recommended course of action based on the status of the account associated with the specified email address.

For example:
This email address already exists in our database. <a href="/activate-account?email=test@example.net">Please create your account here.</a>
checkSignIn
Return Value:  None
Call this method to verify if the specified username (or email address) and password combination is valid and can be used to sign in.
options
username Required
Type:  string
The username (or email address) to verify.
password Required
Type:  string
The password to verify.
lang
Type:  string
Localizes some of the returned values. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
result object: data
allowSignIn
Type:  bool
Indicates if the specified credentials are valid and can be used to sign in.
userID
Type:  int
ID of the user who can be signed in (note: userID is only returned if the specified credentials are valid and can be used to sign in).
responseCode
Type:  string
This keyword indicates why this attempt to sign in is allowed or denied. The following values are possible:
credentialsInvalid
The specified username (or email address) and password combination is not valid.
credentialsRequired
No username (or email address) and/or password was specified.
accountBlocked
The account has been blocked by the festival. The user must be asked to contact the festival.
accountNotActivated
Although the credentials are valid, the account is not yet activated. The user must be asked to activate the account or request a new password.
ok
Signing in is allowed - the specified username (or email address) and password combination is valid and belongs to an active, non-blocked account.
message
Type:  string Localized

Suggested message to display to the user who is trying to sign in.

For example:
Invalid username or password. Please check your username and password, then try again.
getAccreditations
Return Value:  None
Requests all accreditations in a specified event, optionally filtered by accreditation status.
options
eventID Required
Type:  int
Identifies the event of the requested accreditations. Use getEvents to obtain information about existing events, including their IDs.
accreditationStatus
Type:  string
If set, results are restricted to match only accreditations with the specified accreditation status (identified by abbreviation). To match multiple accreditation status values, separate the abbreviations using commas.
columns
Type:  string
Comma-separated string of requested column names. Available columns vary across festivals; see Filmchief System Security Accreditations to find out which columns are available. If not set, the resulting data consists of the columns described below.
callback function: data
accreditationID
Type:  int
The ID of the accreditation.
displayName
Type:  string
The full name of the person associated with the accreditation.
accreditationStatus
Type:  object
This is usually the final status of the accreditation, decided by the festival. It determines whether or not the accreditation is granted. Depending on the festival’s workflow, other meanings may have been attributed to this field. The object has the following properties:
value
Name of the accreditation status, for example "Granted"
id
ID of the accreditation status label
abbreviation
Abbreviation (internal name) of the accreditation status, for example "granted"
color
Hexadecimal color code of the accreditation status, for example "#E91E63"
badgeType
Type:  object
This usually indicates which badge the accredited guest receives. Depending on the festival’s workflow, other meanings may have been attributed to this field. The object has the following properties:
value
Name of the badge type, for example "Press"
id
ID of the badge type label
abbreviation
Abbreviation (internal name) of the badge type, for example "press"
color
Hexadecimal color code of the badge type, for example "#E91E63"
capacityUserOrganization
Type:  object
Describes in which professional capacity the guest is attending the event. The object has the following properties:
value
Name at organization, for example "Kathy Jones at Future Media"
occupation
Function at organization, for example "Director at Future Media"
personnel
Name: Function, for example "Kathy Jones: Director"
userDisplayName
Name of the person, for example "Kathy Jones"
function
Function title, for example "Director"
organization
Name of the organization, for example "Future Media"
id
ID of the occupation (the relation between the person and the organization)
uid
ID of the person (corresponds with userID)
oid
ID of the organization (corresponds with organizationID)
arrivalDate
Type:  string
Date the guest is expected to arrive, formatted as yyyy-mm-dd.
departureDate
Type:  string
Date the guest is expected to leave, formatted as yyyy-mm-dd.

Example:

The following example retrieves information about all granted or pre-approved accreditations of the event with eventID 1:

<?php $params = array( 'token' => $filmchiefApiConnection['token'], 'proc' => 'getAccreditations', 'eventID' => 1, 'accreditationStatus' => 'granted,preapproved' ); $url = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?' . http_build_query($params); $data = json_decode(file_get_contents($url), true); ?>

https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?token=«token»&proc=getAccreditations&eventID=1&accreditationStatus=granted,preapproved
getAuthenticatedUrl
Return Value:  None
Converts a URL (within the festival's filmchief.com subdomain) to a personalized link (also known as a "magic link"). When following a personalized link, the associated user is immediately signed in. If the user record is not yet associated with an account, the account will be immediately activated and the user will be asked to set a password, then taken to the targeted page.
options
userID Required
Type:  int
The ID of the user record to generate a personalized link for.
url Required
Type:  string
URL of the targeted page. This can be either a full URL or a path.
expirationTime
Type:  int
An ISO 8601 duration string that defines for how long the link remains valid, for example 'P10D'. Verbal formats (such as '10 days') are also supported by the parser - see https://php.net/manual/en/dateinterval.createfromdatestring.php for some examples. The default value is defined in settings.personalLinksExpirationTime (typically 90 days).
result object: data
url
Type:  string
The generated personal link.

Make sure to share this link only with the person who owns the associated user record!
expires
Type:  int
UNIX timestamp of when the personal link expires.
getCreditDetails
Return Value:  None
Requests all details of a credit identified by creditID.
options
creditID
Type:  int
Identifies the requested credit by its ID.
callback function: data
* All properties of the requested credit. See Filmchief System Security Credits for more details.
getData
Return Value:  None
This is the most universal method to request data from any specific table. The result set can be restricted to certain columns or rows (using filters), and it can be sorted.
options
table Required
Type:  string or int
Identifies the table (by ID or internal table name) from which data is requested. Commonly used tables are: accreditation, event, film, filmCopy, location, organization, program, programLine, user, viewing. See Filmchief System Security Table-level permission defaults for a complete list of existing tables. You will find the internal table name of any table on its details page.
columns
Type:  string
Comma-separated string of requested column names. Available columns vary across festivals; in Filmchief, see the details page of the selected table to find out which columns are available. If not set, all columns are included.
filters
Type:  string

Filters can be used to restrict the data by certain criteria. You can define one or more filter using a special filter syntax. There are different types of filters, for various types of columns:

Foreign key filters

Columns that directly refer to another table can be filtered like this:

value -column film.submittedForEvent [10]
This filter selects films that were submitted for the event with ID 10. To select all films that were submitted for two events, you can comma-separate the ID values:

value -column film.submittedForEvent [9,10]
This filter selects films that were submitted for the event with ID 9 or 10.

Tags (many-to-many relations) filters

To filter by labels/tags or other fields with a many-to-many relationship, use the option-values filter to find records with matching IDs:

option-values -column film.shownInEvents [10]
This filter selects films that were screened in the event with ID 10. Again, use commas to separate multiple IDs:

option-values -column film.shownInEvents [9,10]
This filter selects films that were screened in the event with ID 9 or 10.

Tags filter modes

For tags filters, the -mode parameter controls how the filter works. Possible options are:

  • or: checks if any of the specified values match
  • and: checks if all of the specified values match
  • not: checks if none of the specified values match

Some examples:

option-values -column film.shownInEvents -mode and [9,10]
This filter selects films that were screened both in the event with ID 9 and 10.

option-values -column film.shownInEvents -mode not [9,10]
This filter selects films that were neither screened in the event with ID 9 nor 10.

Filtering tags by abbreviation

Some labels (tags) have an Abbreviation, which makes them easier to filter. Instead of option-values, use abbreviation to filter by the abbreviation of tags. For example:

abbreviation -column event.eventType ["main"]
This filter selects events with event type "Main event" using the abbreviation of the "event type" label.

Finding records with no tags

To include the Not set option in your filter, use the null keyword as a filter value. For example:

option-values -column event.eventType [null]
This filter selects events with no event type. This also works with the abbreviation filter.

Range filters

Use a range filter to find records with a value between a certain range.

range -column review.rating -min 2 -max 4
This filter selects reviews with a rating between 2 and 4.

range -column history.lastCascadedChange -min 2021-05-09 00:00:00
This filter selects records from the history table for rows that were changed (directly or indirectly) since 9 May 2021.

Text filters

text -column film.originalTitle -mode contains ["now"]
This filter selects films of which the Original title contains the text 'now'.

Text filter modes

For text filters, the -mode parameter controls how the text filter works. Possible options are:

  • contains: checks if the specified text occurs in the specified column
  • does-not-contain: checks if the specified text doesn't occur in the specified column
  • empty: checks if the cell is empty
  • nonempty: checks if the cell is non-empty

Combining multiple filters

Multiple filters are separated with a | character.

option-values -column film.shownInEvents [10]|abbreviation -column film.premiere -mode not [null,"no-premiere"]
This filter selects films that were screened in the event with ID 10, with any Premiere tag.
orderBy
Type:  string
Comma-separated string of column names to sort the data by, optionally suffixed with + (ascending) or - (descending) to indicate sort direction.
limitStart
Type:  int
The row number after which the limited rows are returned. Note: An orderBy clause is not required; however, without an orderBy clause, the results are non-deterministic because results within a result set are not necessarily in any particular order. To control the results returned, use an orderBy clause.
limitCount
Type:  int
The number of rows returned. Note: An orderBy clause is not required; however, without an orderBy clause, the results are non-deterministic because results within a result set are not necessarily in any particular order. To control the results returned, use an orderBy clause.
callback function: data
* All requested columns.

Example:

The following example retrieves event ID, name, publication level, start and end date of all main events, sorted by descending start date:

<?php $params = array( 'token' => $filmchiefApiConnection['token'], 'proc' => 'getData', 'table' => 'event', 'columns' => 'eventID,name,publicationLevel,startDate,endDate', 'filters' => 'abbreviation -column event.eventType ["main"]', 'orderBy' => 'startDate-' ); $url = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?' . http_build_query($params); $data = json_decode(file_get_contents($url), true); ?>

https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?token=«token»&proc=getData&table=event&columns=eventID,name,publicationLevel,startDate,endDate&filters=abbreviation%20-column%20event.eventType%20["main"]&orderBy=startDate-
getEvents
Return Value:  None
Requests basic information about all events or a selection of events, based on the specified criteria.
options
year
Type:  int
If set, results are restricted to match only events in the specified year.
eventType
Type:  string or int
If set, results are restricted to match only events of the specified type (identified by ID or abbreviation). Normally, the abbreviation main represents the annual main event of the festival.
callback function: data
eventID
Type:  int
The ID of the event.
name
Type:  string
The full name of the event.
eventType
Type:  object
Information about the type of event. The object has the following properties:
value
Name of the event type, for example "Main event"
id
ID of the event type label
abbreviation
Abbreviation (internal name) of the event type, for example "main"
color
Hexadecimal color code of the event type, for example "#E91E63"
startDate
Type:  string
Start date of the event, formatted as yyyy-mm-dd.
endDate
Type:  string
End date of the event, formatted as yyyy-mm-dd.

Example:

The following example requests information about all main events that took place in 2023:

<?php $params = array( 'token' => $filmchiefApiConnection['token'], 'proc' => 'getEvents', 'year' => 2023, 'eventType' => 'main' ); $url = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?' . http_build_query($params); $data = json_decode(file_get_contents($url), true); ?>

https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?token=«token»&proc=getEvents&year=2023&eventType=Main%20event
getEventDetails
Return Value:  None
Requests all details of an event identified by eventID or name.
options
eventID
Type:  int
Identifies the requested event by its ID. Either eventID or name is required.
name
Type:  string
Identifies the requested event by its name. Either eventID or name is required.
callback function: data
* All properties of the requested event. See Filmchief System Security Events for more details.
getEventViewingSchedule
Return Value:  None
Requests detailed information about an event identified by eventID, which can be used to build a time schedule.
options
eventID
Type:  int Required
Identifies of which event viewing schedule information is requested.
timelineMode
Type:  string
Defines how the range of the schedule’s timeline is calculated. The following values are allowed:
default
Use the festival’s defaults
full
Use the full range (0-24 hours)
exact
Use the range specifed by firstHourSlot and lastHourSlot
optimal
Automatically determine which range optimally shows all program blocks
firstHourSlot
Type:  int
The hour of day of the earliest timeslot in the schedule. Must be between 0 and 23.
Default:  See Filmchief System Settings Event schedule default settings. The global default value can be overridden at Event level.
lastHourSlot
Type:  int
The hour of day of the latest timeslot in the schedule. Must be between 0 and 23.
Default:  See Filmchief System Settings Event schedule default settings. The global default value can be overridden at Event level.
dayOffset
Type:  int
The hour of day that signifies a new festival day. Since some programs (parties) start after midnight but should be kept together with the preceding day’s program, set this to (for example) 6, when the are no more nighttime programs.
Default:  Depends on timelineMode:
default
6
full
firstHourSlot
exact
firstHourSlot
optimal
Automatically calculated (matching firstHourSlot)
includeReservedTime
Type:  bool
Specifies whether to include the preparation time in the schedule data.
Default:  false
closedProgramsDisplayMode
Type:  string
Defines which programs are included in the schedule. The following values are allowed:
auto
Hide closed programs/viewings, include public viewings
always
All programs/viewings, including closed
public
Include only public programs
closed
Include only closed programs
Default:  auto
showConceptViewings
Type:  bool
undocumented
showCanceledViewings
Type:  bool
undocumented
minDuration
Type:  int
undocumented
maxDuration
Type:  int
undocumented
programTypes
Type:  string (comma-separated values)
undocumented
programStatus
Type:  string (comma-separated values)
undocumented
viewingStatus
Type:  string (comma-separated values)
undocumented
departmentsInvolved
Type:  string (comma-separated values)
undocumented
programLines
Type:  string (comma-separated values)
Comma-separated ID values of program lines to filter viewings by.
callback function: data
scheduleInfo
Type:  object
General information about the schedule.
viewings
Type:  array of objects
Each object in this array contains all properties of a viewing in the requested event. See Filmchief System Security Viewings for more details.
programLines
Type:  array of objects
Each object in this array contains all properties of a program line in the requested event. Use this data to build the schedule’s legend.
getFilmCopyDetails
Return Value:  None
Requests all details of a film copy identified by filmCopyID.
options
filmCopyID
Type:  int
Identifies the requested film copy by its ID.
callback function: data
* All properties of the requested film copy. See Filmchief System Security Film copies for more details.
getFilmCredits
Return Value:  None
Requests all details of credits of the specified film, identified by filmID or idNr.
options
filmID
Type:  int
Identifies the requested film by its internal ID (referred to as filmID).
idNr
Type:  string
Identifies the requested film by its external ID (as used by the festival, referred to as idNr).
callback function: data
* All credits of the requested film. See Filmchief System Security Credits for more details.
getFilmDetails
Return Value:  None
Requests all details of a film identified by filmID or idNr.
options
filmID
Type:  int
Identifies the requested film by its internal ID (referred to as filmID).
idNr
Type:  string
Identifies the requested film by its external ID (as used by the festival, referred to as idNr).
callback function: data
* All properties of the requested film. See Filmchief System Security Films for more details.
getFilmsShownInEvent
Return Value:  None
Requests specified columns of films shown in the specified event (identified by eventID).
options
eventID
Type:  int
Identifies the event.
columns
Type:  string
Comma-separated string of requested column names. Available columns vary across festivals; see Filmchief System Security Films to find out which columns are available.
callback function: data
* Requested properties of films shown in the specified event.
getImage deprecated
Return Value:  None
Returns a URL to an image, optionally scaled to meet specified constraints.

Note: this method is deprecated: please see File access for a more powerful and easier to use solution.

options
uploadedFileID
Type:  int
Identifies the requested image by its ID.
maxWidth
Type:  int
Optional maximum width in pixels.
maxHeight
Type:  int
Optional maximum height in pixels.
minWidth
Type:  int
Optional minimum width in pixels.
minHeight
Type:  int
Optional minimum height in pixels.
coverWidth
Type:  int
Optional width (in pixels) to make the image cover at least a certain area (use in conjunction with coverHeight). Best combined with cropWidth and cropHeight.
coverHeight
Type:  int
Optional height (in pixels) to make the image cover at least a certain area (use in conjunction with coverWidth). Best combined with cropWidth and cropHeight.
cropWidth
Type:  int
Optional width (in pixels) to crop the image to (applied after scaling).
cropHeight
Type:  int
Optional height (in pixels) to crop the image to (applied after scaling).
quality
Type:  int
Optional compression quality setting (1-100). A value of 100 represents best quality, least compression. Default quality is 80.
callback function: data
fileUrl
Type:  string
URL of the (scaled) image, URL-encoded according to RFC 3986
getListData
Return Value:  None
Requests data from any existing list. You may select all records from a list, or a paginated subset.
options
listID Required
Type:  int
Identifies the list (by ID) of which data is requested.
parameterValues
Type:  string
Some lists require one or more parameter values, which determine the selected records. Note: this currently only applies to internal Filmchief lists, so you can safely ignore this option.
limitStart
Type:  int
Set to specify the offset of the selected records. This corresponds with the OFFSET value in an SQL LIMIT clause.
limitCount
Type:  int
Set to any positive integer value to limit the result set to the specified number of rows. This corresponds with the COUNT value in an SQL LIMIT clause. If omitted, getListData assumes the page size of the selected list. Set to 0 to select all records from the list.
callback function: data
listData
Type:  object (table)
Array of all selected records.
recordInfo
Type:  object
Various key-value pairs that provide general information about the selected records.
getMeetings
Return Value:  None
Requests all meetings in the specified event.
options
eventID Required
Type:  int
Identifies the requested event by its ID.
callback function: data
*
Type:  array of <Meeting>
Array of requested meetings, in no particular order. See Filmchief System Security Meetings for more details.
getOnlineResources
Return Value:  None
Requests all online resources in the specified event, or all online resources used in the specified viewing.
options
eventID
Type:  int
Identifies the requested event by its ID.
viewingID
Type:  int
Identifies the requested viewing by its ID. If viewingID is specified, there is no need to also specify eventID.
callback function: data
*
Type:  array of <OnlineResource>
Array of requested online resources, in no particular order. See Filmchief System Security Online resources for more details.
getOrderDetails
Return Value:  None
Requests all details of a order identified by orderID.
options
orderID Required
Type:  int
Identifies the requested order by its ID.
lang
Type:  string
If set, some results are localized to the specified language. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
callback function: data
*

All properties of the requested order. See Filmchief System Security Orders for more details.

Some notable fields include:

requested
Type:  tinyint (0 or 1)
Indicates if the order is a requested payment (1) or a shopping cart (0).
completed
Type:  tinyint (0, 1 or 2)
Indicates the transaction status of this order:

0: the transaction has not started
1: waiting for the transaction to complete
2: transaction complete
processed
Type:  tinyint (0, 1 or 2)
This indicates the processing status of this order. During order processing, Filmchief may generate tickets, assign passes, generate a receipt PDF, and send a payment confirmation email. Order processing starts immediately after the transaction has completed. Possible status values are:

0: the order has not yet been processed
1: busy processing the order
2: processing complete
currency
Type:  object

Currency of all prices in this order. This object consists of the following properties:

id
Type:  int
Internal ID of this currency.
currency
Type:  string
Three letter ISO-4217 currency code, e.g. "EUR".
symbol
Type:  string
Symbol of this currency, e.g. "€".
unitText
Type:  string
Name of this currency, e.g. "Euro".
value
Type:  string
Reference value (shown when this currency is referenced from another table).
totalPriceTaxIncluded
Type:  int/string

Total price of this order, including tax.

Note: because of floating-point issues in JavaScript (and JSON), values with fractions are stored as a string (e.g. "2.05").
summaryExternal
Type:  string (html) Localized
Compact description of the ordered products, each product separated by <br>, in the specified language. This field is recommended to be displayed to the user, to show what they are buying.
getOrganizationDetails
Return Value:  None
Requests all details of an organization identified by organizationID.
options
organizationID
Type:  int
Identifies the requested organization by its ID.
callback function: data
* All properties of the requested organization. See Filmchief System Security Organizations for more details.
getProgramDetails
Return Value:  None
Requests all details of a program identified by programID.
options
programID
Type:  int
Identifies the requested program by its ID.
callback function: data
* All properties of the requested program. See Filmchief System Security Programs for more details.
getProgramItems
Return Value:  None
Requests all items of a program identified by programID.
options
programID
Type:  int
Identifies the requested program by its ID.
callback function: data
*
Type:  array of <ProgramItem>
All items of the requested program, in chronological order. See Filmchief System Security Program items for more details.
getProgramLineDetails
Return Value:  None
Requests all details of a program line identified by programLineID.
options
programLineID
Type:  int
Identifies the requested program line by its ID.
callback function: data
* All properties of the requested program line. See Filmchief System Security Program lines for more details.
getProgramLines
Return Value:  None
Requests program lines in the specified event. Either all program lines, or only the main program lines are returned.
options
eventID
Type:  int
Identifies the requested event by its ID. If no event is specified, program lines from all events are returned.
recursive
Type:  bool (default: true)
When true, all program lines in the event are returned. When false, only the main program lines of the event are returned.
callback function: data
*
Type:  array of <ProgramLine>
Array of requested program lines, ordered by hierarchial position (i.e. depth-first, like a Tree view). See Filmchief System Security Program lines for more details.
getPrograms
Return Value:  None
Requests all programs in the specified event or program line.
options
eventID
Type:  int
Identifies the requested event by its ID.
programLineID
Type:  int
Identifies the requested program line by its ID. If programLineID is specified, there is no need to also specify eventID.
callback function: data
*
Type:  array of <Program>
Array of requested programs, ordered by position in the program line. If the results cover multiple program lines, the program lines are ordered hierarchically (i.e. depth-first, like a Tree view). See Filmchief System Security Programs for more details.
getTicketingDetails
Return Value:  None

Requests information relevant for ticketing of one or more viewings.

Note: if eventID, programID and viewingID are not set, then all viewings in all current and future events are selected.

options
eventID
Type:  int
If set, results are restricted to viewings that are part of the requested event.
programID
Type:  int
If set, results are restricted to viewings of the requested program.
viewingID
Type:  string
If set, results are restricted to the requested viewing (or comma-separated viewings) only.
currentUserID
Type:  int
ID of the currently signed in user. If there are price levels available only to this user, they will be included in the results.
pointOfSaleTypes
Type:  string
Comma-separated ID values or abbreviation values of point of sale types to filter ticket types and price levels by.

If you are integrating ticketing in your festival site, specify online to restrict to tickets that are available online.
lang
Type:  string
ID or code of the current interface language, e.g. 'en' or 'nl'.
onSaleNow
Type:  int
Set to 1 to exclude tickets that are no longer / not yet available.
addSeconds
Type:  int
Simulates another time by adding or subtracting seconds. Useful for previewing and debugging.
callback function: data
*
Type:  array
The data object is an array of requested viewings, including ticketing information. Each element consists of the following properties:
viewingID
Type:  int
The ID of the viewing.
startDateTime
Type:  string (datetime)
Date and time this viewing starts. Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
locationLabel
Type:  string
The location where the viewing takes place.
programTitle
Type:  string
Title of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
programSubtitle
Type:  string
Secondary title of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
programShortDescription
Type:  string (html)
Short description of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
programLongDescription
Type:  string (html)
Long description of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
saleStartDateTime
Type:  string (datetime)
Date and time when ticket sales for this viewing start. Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
saleEndDateTime
Type:  string (datetime)
Date and time when ticket sales for this viewing (of any type or price level) end. This also takes into account the viewing’s start date/time and the Checkout deadline (global value or viewing-specific override). Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
onSaleNow
Type:  int (0 or 1)
Indicates if tickets for this viewing (of any type or price level) are on sale right now (or at the simulated time, if addSeconds is set to a non-zero value). This takes into account the sale period, as well as the viewing’s start date/time and the global Checkout deadline setting. For example, if a viewing starts at 17:00 and the checkout deadline is set to -15, then (online) ticket sales end at 16:45.
currencySymbol
Type:  string
Currency symbol to use when displaying price information (see priceAmount below).
ticketsRemaining
Type:  int
The total number of tickets remaining for this viewing.

If this value is 0, it means that tickets for this viewing are sold out; make sure to communicate this with your customers.

If tickets are almost running out, you can display an "Almost sold out!" notification to encourage customers to hurry up.
ticketingDetails
Type:  array
Array of available ticket types and price levels for this viewing. Each element has the following properties:
productID
Type:  int
The ID of the product (ticket type).
productName
Type:  string
Name of this product, e.g. "Regular ticket".
productDescription
Type:  string
Description of this product, e.g. "Regular ticket price for online sales".
promotionID
Type:  int
The ID of the promotion (= price level), if any.
promotionName
Type:  string
Name of this price level, e.g. "Early bird reduction".
promotionDescription
Type:  string
Description of this product, e.g. "Special reduced price (20% off) For our early bird customers.".
saleStartDateTime
Type:  string (datetime)
Date and time when ticket sales of this ticket type and price level (if set) start. Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
saleEndDateTime
Type:  string (datetime)
Date and time ticket sales for this viewing of this ticket type and price level (if set) end. This also takes into account the viewing’s start date/time and the Checkout deadline (global value or viewing-specific override). Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
onSaleNow
Type:  int (0 or 1)
Indicates if tickets for this viewing of this ticket type and price level (if set) are on sale right now. This takes into account the sale period, as well as the viewing’s start date/time and the Checkout deadline (global value or viewing-specific override). For example, if a viewing starts at 17:00 and the checkout deadline is set to -15, then (online) ticket sales end at 16:45.
priceAmount
Type:  decimal(7,2)
Effective price per ticket (including VAT).
priceNote
Type:  string
Additional information about the specified price, e.g. "40% discount".
promotionAccreditationListID
Type:  int
The ID of a list that defines which guests (accreditations) are eligible for this price level.

If this value is not null, you can inform your customer that "Conditions apply" or something along those lines. On the Cart and Checkout pages, Filmchief will verify if the customer is actually eligible.
promotionCodeSets
Type:  string
Comma-separated IDs of promotion code sets applicable to this price level.

If this value is not null, you can display a "Promotion code required" notification. On the Cart page, the customer can enter the required promotion code.

Example:

The following example retrieves online ticketing information of all viewings in a particular program (with programID = 598) for the currently signed in user.

Note how the value for currentUserID is taken from the $_SESSION['«FESTIVAL IDENTIFIER».filmchief.com'] object, which is automatically defined if SSO is enabled for your website (please see the Single sign-on documentation).

<?php // By default, assume no user is currently signed in: $currentUserID = null; // Check if session information from Filmchief is available: if (isset($_SESSION['«FESTIVAL IDENTIFIER».filmchief.com']) && isset($_SESSION['«FESTIVAL IDENTIFIER».filmchief.com']['userID'])) { // Get the ID of the currently signed in user (at the Filmchief Portal): $currentUserID = $_SESSION['«FESTIVAL IDENTIFIER».filmchief.com']['userID']; } // Define API call parameters: $params = array( 'token' => $filmchiefApiConnection['token'], 'proc' => 'getTicketingDetails', 'programID' => 598, 'currentUserID' => $currentUserID, 'pointOfSaleTypes' => 'online', 'onSaleNow' => 1 ); // Contruct the API call URL: $url = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?' . http_build_query($params); // Retrieve and decode the API call results: $data = json_decode(file_get_contents($url), true); ?>

https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?token=«token»&proc=getTicketingDetails&programID=598&currentUserID=«currentUserID»&pointOfSaleTypes=online&onSaleNow=1

Example response:
{ "data": [ { "viewingID": 698, "startDateTime": "2019-11-15 12:00:00Z", "locationLabel": "Ketelhuis 1", "programTitle": "Dutch Classics I: Musical Encounters", "programSubtitle": "", "programShortDescription": null, "programLongDescription": null, "onSaleNow": 1, "saleStartDateTime": "2020-09-03T11:00:00Z", "saleEndDateTime": "2019-11-15T11:45:00Z", "currencySymbol": "€", "ticketingDetails": [ { "productID": 11, "saleStartDateTime": "2019-09-02T14:29:00Z", "productName": "Regular Ticket Test", "productDescription": "Regular Ticket Test", "saleEndDateTime": "2019-11-15T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 10, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null }, { "productID": 12, "saleStartDateTime": "2019-09-02T14:33:00Z", "productName": "Student Tickets Test", "productDescription": "Student Tickets Test", "saleEndDateTime": "2019-11-15T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 8, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null }, { "productID": 13, "saleStartDateTime": "2019-09-02T14:39:00Z", "productName": "Kid Tickets Test", "productDescription": "Kid Tickets Test", "saleEndDateTime": "2019-11-15T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 6.5, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null } ], "ticketsRemaining": 143 }, { "viewingID": 699, "startDateTime": "2019-11-16 12:00:00Z", "locationLabel": "Ketelhuis 3", "programTitle": "Dutch Classics I: Musical Encounters", "programSubtitle": "", "programShortDescription": null, "programLongDescription": null, "onSaleNow": 1, "saleStartDateTime": "2019-09-02T14:29:00Z", "saleEndDateTime": "2019-11-16T11:45:00Z", "currencySymbol": "€", "ticketingDetails": [ { "productID": 11, "saleStartDateTime": "2019-09-02T14:29:00Z", "productName": "Regular Ticket Test", "productDescription": "Regular Ticket Test", "saleEndDateTime": "2019-11-16T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 10, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null }, { "productID": 12, "saleStartDateTime": "2019-09-02T14:33:00Z", "productName": "Student Tickets Test", "productDescription": "Student Tickets Test", "saleEndDateTime": "2019-11-16T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 8, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null }, { "productID": 13, "saleStartDateTime": "2019-09-02T14:39:00Z", "productName": "Kid Tickets Test", "productDescription": "Kid Tickets Test", "saleEndDateTime": "2019-11-16T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 6.5, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null } ], "ticketsRemaining": 50 }, { "viewingID": 700, "startDateTime": "2019-11-17 12:00:00Z", "locationLabel": "Machinegebouw Grote zaal (4)", "programTitle": "Dutch Classics I: Musical Encounters", "programSubtitle": "", "programShortDescription": null, "programLongDescription": null, "onSaleNow": 1, "saleStartDateTime": "2019-09-02T14:29:00Z", "saleEndDateTime": "2019-11-17T11:45:00Z", "currencySymbol": "€", "ticketingDetails": [ { "productID": 11, "saleStartDateTime": "2019-09-02T14:29:00Z", "productName": "Regular Ticket Test", "productDescription": "Regular Ticket Test", "saleEndDateTime": "2019-11-17T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 10, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null }, { "productID": 12, "saleStartDateTime": "2019-09-02T14:33:00Z", "productName": "Student Tickets Test", "productDescription": "Student Tickets Test", "saleEndDateTime": "2019-11-17T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 8, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null }, { "productID": 13, "saleStartDateTime": "2019-09-02T14:39:00Z", "productName": "Kid Tickets Test", "productDescription": "Kid Tickets Test", "saleEndDateTime": "2019-11-17T11:45:00Z", "promotionID": null, "promotionName": null, "promotionDescription": null, "priceAmount": 6.5, "priceNote": null, "promotionAccreditationListID": null, "promotionCodeSets": null } ], "ticketsRemaining": 180 } ], "accepted": true }
getUserDetails
Return Value:  None
Requests all or specified details of a person identified by userID.
options
userID
Type:  int
Identifies the requested person by its ID.
columns
Type:  string
Comma-separated string of requested column names. Available columns vary across festivals; see Filmchief System Security People to find out which columns are available. If not set, the resulting data consists of the all available columns.
callback function: data
* All properties of the requested person. See Filmchief System Security People for more details.
getViewings
Return Value:  None
Requests all viewings in the specified event, or all viewings of the specified program.
options
eventID
Type:  int
Identifies the requested event by its ID.
programID
Type:  int
Identifies the requested program by its ID. If programID is specified, there is no need to also specify eventID.
minStartDateTime
Type:  datetime
Minimum startDateTime value. Use this parameter to only select viewings that start after (or at) the specified date and time. The date and time must be formatted as yyyy-mm-dd hh:mm:ss.
maxStartDateTime
Type:  datetime
Maximum startDateTime value. Use this parameter to only select viewings that start before (or at) the specified date and time. The date and time must be formatted as yyyy-mm-dd hh:mm:ss.
callback function: data
*
Type:  array of <Viewing>
Array of requested viewings, ordered chronologically. See Filmchief System Security Viewings for more details.

Writer module

A service for modifying data on Filmchief.

Endpoint
To use any of the methods in the Writer module, call the following URL:
https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Writer
token
In each API call, you must specify the token obtained in the authorization call described above.
proc
The requested method.
+ method parameters
Include the parameters of the requested method in your API call.
Methods
inAppPurchaseComplete
Return Value:  None

Call this method to register the in-app purchase of a single product by the app user. Based on the specified user and product, an order is created, validated, completed, and processed. Depending on the sold product type, Filmchief may generate a ticket, assign a pass. It will generate a receipt PDF and send a payment confirmation email.

Note: order processing may take up to a minute to complete.

options
userID Required
Type:  int
ID of the user (i.e. the customer).
productID Required
Type:  int
ID of the product that is sold to the customer.
lang
Type:  string
If set, the payment confirmation email is sent in the specified language. If not set, the preferred language of the customer's user account is used. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
[accepted] result object: data
invoiceLinkUrl
Type:  string
URL to download the receipt PDF.
[not accepted] result object: rejectedReason
message
Type:  string
Describes why the order could not be completed.
code
Type:  string

This keyword indicates why the order could not be completed. The following values are possible:

databaseReadOnly
The database is in read-only mode.
missingParameters
No user ID or product ID was specified.
userNotFound
No user record exists with the specified user ID.
productNotFound
No product record exists with the specified product ID.
productNotInApp
The specified product is not available for in-app purchases.
productNotAddedToOrder
Failed to add the specified product to the order. This error should never occur - contact Filmchief support if it does.
orderNotReady
Failed to generate a checkout URL for the newly created order. This error should never occur - contact Filmchief support if it does.
inAppRequestedOrderComplete
Return Value:  None

Call this method to mark the order of an in-app payment request as complete, and to start processing the order. When an order is processed, depending on which products are sold, Filmchief may generate tickets, assign passes, generate a receipt PDF, and send a payment confirmation email.

options
orderID Required
Type:  int
ID of the order to complete and process.
lang
Type:  string
If set, the payment confirmation email is sent in the specified language. If not set, the preferred language of the customer's user account is used. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
[accepted] result object: data
invoiceLinkUrl
Type:  string
URL to download the receipt PDF.
[not accepted] result object: rejectedReason
message
Type:  string
Describes why the order could not be completed.
code
Type:  string

This keyword indicates why the order could not be completed. The following values are possible:

databaseReadOnly
The database is in read-only mode.
missingParameters
No order ID was specified.
orderNotFound
No order record exists with the specified order ID.
orderAlreadyCompleted
The order was already completed.
update
Return Value:  None
Call this method to directly update a cell in a record, or to add an update statement to an operation.
options
operationID
Type:  int
ID of the operation to which this update is added (if applicable).
tableName Required
Type:  string
Name of the table that is affected.
columnName Required
Type:  string
Name of the affected column in the specified table.
recordID Required
Type:  int
ID of the affected record in the specified table.
value
Type:  string
The value the affected cell will be upated to. If not set, the cell will be set to NULL.
[accepted] result object: data
status
Type:  int
0 if successful.
[not accepted] result object: rejectedReason
message
Type:  string Localized
Describes why the update statement could not be executed or added to the specified operation.
userCreate
Return Value:  None
Call this method to create a new user account. An account activation email will be sent to the specified email address.
options
emailAddress Required
Type:  string
The email address of the new account, to which the account activation email is sent.
password Required
Type:  string
The password of the new account.
lang Required
Type:  string
Sets the preferred language of the new account, and localizes some of the returned values. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
firstName
Type:  string
First name of the person who owns the new account.
surnamePrefix
Type:  string
Surname prefix of the person who owns the new account, e.g. "van der" (in Dutch names). Note: this field may not be in use.
lastName
Type:  string
Last name of the person who owns the new account.
[accepted] result object: data
userID
Type:  int
ID of the created user record (if successful).
confirmationSentTo
Type:  string
Email address the account activation email was sent to.
confirmationSentFrom
Type:  string
Email address the account activation email was sent from.
[not accepted] result object: rejectedReason
message
Type:  string Localized
Describes why the user account could not be created. If rejectedReason.code is one of the keywords listed below, it should be safe to display this message to the end user.
code
Type:  string

This keyword indicates why a new user account could not be created. The following values are possible:

databaseReadOnly
The database is in read-only mode.
blocked
The account has been blocked by the festival. The account must first be unblocked or deleted before the email address can be used again to sign in or create an account.
noAccount
A user record exists, but there is no account. The account can be claimed by requesting an activation token using the link in the rejectedReason.message property of the result data.
activationTokenExpired
Activation link of non-activated account expired - the user did not activate the account in time and must request a new activation token using the link in the rejectedReason.message property of the result data.
activationPending
Waiting for activation - an email with an activation link was sent recently (and it is still valid). The user should be instructed to find that email and click on the activation link.
active
The email address belongs to an active account. Access can be reclaimed by the "Forgot password" procedure.
userDeactivate
Return Value:  None

Call this method to deactivate a user account. From the user's perspective, the account is deleted, but the actual user details are preserved, because the festival may still need it. For instance, the user may be the director of a film; deleting the user record would result in loss of important information.

After deactivation, the user's Status will be marked as "Deactivated account", and the user will no longer be able to sign in using this account.

options
userID Required
Type:  int
ID of the user account to deactivate.
[accepted] result object: none
[not accepted] result object: rejectedReason
message
Type:  string
Describes why the user account could not be deactivated.
code
Type:  string

This keyword indicates why the user account could not be deactivated. The following values are possible:

databaseReadOnly
The database is in read-only mode.
userNotFound
No user record exists with the specified user ID.
userAlreadyDeactivated
The user account was already deactivated.
userReset
Return Value:  None
Call this method to let a user set a new password for their account. The user will receive an email with further instructions.
options
emailAddress
Type:  string
The email address of the account to reset. Note: either emailAddress or username is required.
username
Type:  string
The username of the account to reset. Note: either emailAddress or username is required.
redirectFrom
Type:  string
Optional path of a page to where the user is redirected after having set their new password. For example: "shop/sign-in". If not set, the user will be redirected to the Portal homepage.
lang
Type:  string
If set, the email is sent in the specified language. If not set, the preferred language of the user account is used. Specify a lower-case two-letter ISO-639 language code, optionally followed by an upper-case two-letter ISO-3166 country code, separated with an underscore. For example: "de" for German or "pt_PT" for Portuguese, Portugal.
[accepted] result object: data
confirmationSentTo
Type:  string
Email address the email was sent to.
confirmationSentFrom
Type:  string
Email address the email was sent from.
[not accepted] result object: rejectedReason
message
Type:  string Localized
Describes why the user account could not be reset.
code
Type:  string

This keyword indicates why a new user account could not be created. The following values are possible:

databaseReadOnly
The database is in read-only mode.
missingParameters
No email address or user name was specified.
userNotFound
No user record exists with the specified email address or user name.
{{#files}}
{{value}}
{{/files}}