Fienta API
Base URL

The base URL for Fienta’s API is https://fienta.com/api/v1

Authorization

Fienta uses token based Bearer authorization which is required for protected API endpoints.

The client must send token in the Authorization header when making requests to protected resources:

Authorization: Bearer <token>

Authorization headers
string required
Example:
Authorization: Bearer e0333aa09ed5cc0f3f98af3b5a0689ca
Authentication

There are two ways to get the token:

  1. Organiser account level API key can be found using Fienta’s user interface from Settings > Integration.
  2. User level key can be retrieved via the API using Authenticate call.
Authenticate
POST /auth
Authenticate
POST /auth

Authentication

Open

On successful authentication returns the API token to use for authorization in API request headers.

Request headers

Content-Type
string required
Example:
application/json

Request body

Object
email
string required
Example:
myemail@domainname.com
password
string required
Example:
mypassword
Examples
{
    "email": "myemail@domainname.com",
    "password": "mypassword"
}

Responses

200 OK
Body
Object
success
Success
token
Object required
token
string required

The API token to use for authorization of API requests that require it

Example:
e0333aa09ed5cc0f3f98af3b5a0689ca
expires_at
unknown required nullable

Expiration date and time for the token

Example:
2021-04-30 00:00:00
user_id
integer nullable

The user ID the token is tied to. May be null if the token is tied to a specific organizer or an event instead.

Example:
1
Examples
{
    "success": {
        "code": 200,
        "user_message": "Authenticated successfully",
        "internal_message": "authenticated_successfully"
    },
    "token": {
        "token": "TOKENSTRING",
        "expires_at": null,
        "user_id": 1
    }
}
Common responses
Success
Object
code
integer
Example:
200
user_message
string
internal_message
string
Errors
Object
errors
Array
Object
code
integer

The HTTP status code

Example:
401
user_message
string

Human readable description of the error

Example:
Unauthorized access
internal_message
string

Internal description of the error

Example:
Authorization failed
401 Unauthorized access

Authorization fails due to an invalid token or no permission to access the requested resource.

Body
Errors
Examples

Authorization fails due to an invalid token

{
    "errors": [
        {
            "code": 401,
            "user_message": "Unauthorized access",
            "internal_message": "authorization_failed"
        }
    ]
}

No permission to access the queried resource

{
    "errors": [
        {
            "code": 401,
            "user_message": "Unauthorized access",
            "internal_message": "unauthorized_access_to_resource"
        }
    ]
}
Organizers
Get organizers
GET /organizers
Get events of the organizer
GET /organizers/{organizer_id}/events
Get organizers
GET /organizers

Authentication

Bearer token

Returns organizers the given API token has access to.

Request headers

Authorization headers
string required
Example:
Authorization: Bearer e0333aa09ed5cc0f3f98af3b5a0689ca

Responses

401 Unauthorized access

Authorization fails due to an invalid token or no permission to access the requested resource.

200 OK
Body
Object
success
Success
organizers
Array of Organizer
time
Time
Examples
{
    "success": {
        "code": 200,
        "user_message": "Organizers returned successfully",
        "internal_message": "organizers_returned_successfully"
    },
    "organizers": [
        {
            "id": 4,
            "name": "Organizer Company Name Ltd."
        },
        {
            "id": 7,
            "name": "Another Organizer Name"
        }
    ],
    "time": {
        "timestamp": 1525436423,
        "date": "2018-05-04",
        "time": "15:20:23",
        "full_datetime": "2018-05-04T15:20:23+03:00",
        "timezone": "Europe/Tallinn",
        "timezone_short": "EEST",
        "gmt": "+0300"
    }
}
Get events of the organizer
GET /organizers/{organizer_id}/events

Authentication

Bearer token

Get all events of the organizer specified by organizer_id.

Path variables

organizer_id
string required

Request parameters

starts_from
string optional

Retrive events which start at specified time or later.

Examples:
/organizers/{organizer_id}/events/?starts_from=2020-12-31/organizers/{organizer_id}/events/?starts_from=2020-12-31 20:00
ends_from
string optional

Retrive events which end at specified time or later.

Examples:
/organizers/{organizer_id}/events/?ends_from=2020-12-31/organizers/{organizer_id}/events/?starts_from=2020-12-31 20:00

Request headers

Authorization headers
string required
Example:
Authorization: Bearer e0333aa09ed5cc0f3f98af3b5a0689ca

Responses

401 Unauthorized access

Authorization fails due to an invalid token or no permission to access the requested resource.

200 OK
Body
Object
success
Success
events
Array of Event
time
Time
Examples
{
    "success": {
        "code": 200,
        "user_message": "Events returned successfully",
        "internal_message": "events_returned_successfully"
    },
    "events": [
        {
            "id": 10,
            "title": "Happy event",
            "starts_at": "2018-09-22 00:00:00",
            "ends_at": "2018-10-22 23:59:59",
            "duration_string": "Sat 22. September - Mon 22. October 2018"
        }
    ],
    "time": {
        "timestamp": 1525436423,
        "date": "2018-05-04",
        "time": "15:20:23",
        "full_datetime": "2018-05-04T15:20:23+03:00",
        "timezone": "Europe/Tallinn",
        "timezone_short": "EEST",
        "gmt": "+0300"
    }
}
Tickets
Get tickets of the event
GET /events/{event_id}/tickets/
Get a single ticket
GET /tickets/{ticket_code}/
Update a single ticket
PUT /tickets/{ticket_code}/
Get tickets of the event
GET /events/{event_id}/tickets/

Authentication

Bearer token

Path variables

event_id
integer required

ID of the event

Request parameters

updated_after
string optional

Return only tickets that have been updated after the specified date/time (either a Unix timestamp in seconds or a date/time string accepted by the PHP strtotime function)

Examples:
/events/1234/tickets/?updated_after=1525619967/events/1234/tickets/?updated_after=2018-05-06%2015:19:27
attendees
string optional

The registration form data provided by the ticket holder is omitted by default for reducing data size and optimising database performance. To add the “attendee” object, add “attendees” parameter.

Example:
/events/1234/tickets/?attendees

Request headers

Authorization headers
string required
Example:
Authorization: Bearer e0333aa09ed5cc0f3f98af3b5a0689ca

Responses

401 Unauthorized access

Authorization fails due to an invalid token or no permission to access the requested resource.

200 OK
Body
Object
success
Success required

The success payload

time
Time required
tickets
Array of Ticket required

An array of tickets

Examples
{
    "success": {
        "code": 200,
        "user_message": "",
        "internal_message": ""
    },
    "time": {
        "timestamp": 1525436423,
        "date": "2018-05-04",
        "time": "15:20:23",
        "full_datetime": "2018-05-04T15:20:23+03:00",
        "timezone": "Europe/Tallinn",
        "timezone_short": "EEST",
        "gmt": "+0300"
    },
    "tickets": [
        {
            "id": 87,
            "event_id": 10,
            "order_id": 43,
            "code": "4LO4A3T8IH",
            "status": "UNUSED",
            "used_at": "2018-03-01 15:35:11",
            "created_at": "2018-02-01 13:24:48",
            "updated_at": "2018-02-01 13:24:48",
            "validated_by": 1,
            "ip": "192.168.1.2",
            "contents_html": "<h1>1 x Regular ticket</h1><h1>2 x Student ticket</h1><h2>John</h2><h2>Smith</h2>",
            "nametag_html": "<!DOCTYPE html><html><body><p>Name: John</p><p>Surname: Smith</p></body></html>",
            "qty": 3
        }
    ]
}

Examples

Get tickets for event with ID 10 that were updated after 2018-05-06 15:19:27

GET http://fienta.localhost/api/v1/events/10/tickets/?updated_after=1525619967 HTTP/1.1 

Authorization: Bearer APITOKEN
Get a single ticket
GET /tickets/{ticket_code}/

Authentication

Bearer token

Path variables

ticket_code
string required

Code of the ticket

Example:
4LO4A3T8IH

Request parameters

atendees
string optional

The registration form data provided by the ticket holder is omitted by default for reducing data size and optimising database performance. To add the “attendee” object, add “attendees” parameter.

Example:
/tickets/W92YGGA0A8/?attendees

Request headers

Authorization headers
string required
Example:
Authorization: Bearer e0333aa09ed5cc0f3f98af3b5a0689ca

Responses

401 Unauthorized access

Authorization fails due to an invalid token or no permission to access the requested resource.

200 OK
Body
Object
success
Success required

The success payload

time
Time
ticket
Ticket required
Examples
{
    "success": {
        "code": 200,
        "user_message": "",
        "internal_message": ""
    },
    "ticket": {
        "id": 87,
        "event_id": 10,
        "order_id": 43,
        "order_email": "john@smidth.com",
        "code": "4LO4A3T8IH",
        "status": "UNUSED",
        "used_at": "2018-03-01 15:35:11",
        "created_at": "2018-02-01 13:24:48",
        "updated_at": "2018-02-01 13:24:48",
        "validated_by": 1,
        "ip": "192.168.1.2",
        "contents_html": "<h1>1 x Regular ticket</h1><h1>2 x Student ticket</h1><h2>John</h2><h2>Smith</h2>",
        "nametag_html": "<!DOCTYPE html><html><body><p>Name: John</p><p>Surname: Smith</p></body></html>",
        "qty": 3
    },
    "time": {
        "timestamp": 1525436423,
        "date": "2018-05-04",
        "time": "15:20:23",
        "full_datetime": "2018-05-04T15:20:23+03:00",
        "timezone": "Europe/Tallinn",
        "timezone_short": "EEST",
        "gmt": "+0300"
    }
}
Update a single ticket
PUT /tickets/{ticket_code}/

Authentication

Bearer token

Path variables

ticket_code
string required

Code of the ticket

Request headers

Authorization headers
string required
Example:
Authorization: Bearer e0333aa09ed5cc0f3f98af3b5a0689ca

Request body

Object
status
string required

One of the following: USED, UNUSED, REFUND_REQUESTED

Example:
USED
used_at
string

Date and time the ticket was validated

Example:
"2018-04-06 22:27:21"
Examples
{
    "status": "USED",
    "used_at": "2018-04-06 22:27:21"
}
{
    "status": "UNUSED",
    "used_at": null
}

Responses

401 Unauthorized access

Authorization fails due to an invalid token or no permission to access the requested resource.

200 OK
Body
Object
success
Success
time
Time
Examples
{
    "success": {
        "code": 200,
        "user_message": "Ticket updated successfully",
        "internal_message": "ticket_updated_successfully"
    },
    "time": {
        "timestamp": 1525436423,
        "date": "2018-05-04",
        "time": "15:20:23",
        "full_datetime": "2018-05-04T15:20:23+03:00",
        "timezone": "Europe/Tallinn",
        "timezone_short": "EEST",
        "gmt": "+0300"
    }
}
Time
Get server time
GET /server_time/
Get server time
GET /server_time/

Authentication

Open

Get the current server date, time and timezone values

Responses

200 OK
Body
Object
success
Success
time
Time
Examples
{
    "success": {
        "code": 200,
        "user_message": "Timestamp returned successfully",
        "internal_message": "timestamp_returned_successfully"
    },
    "time": {
        "timestamp": 1525436423,
        "date": "2018-05-04",
        "time": "15:20:23",
        "full_datetime": "2018-05-04T15:20:23+03:00",
        "timezone": "Europe/Tallinn",
        "timezone_short": "EEST",
        "gmt": "+0300"
    }
}
Data reference
Time
Object
timestamp
integer

Unix timestamp (seconds since January 1st 1970)

Example:
1525436423
date
string

Date formatted in PHP date format “Y-m-D”

Example:
2018-05-04
time
string

Time formatted in PHP date format “H:i:s”

Example:
15:20:23
full_datetime
string

Full datetime string

Example:
2018-05-04T15:20:23+03:00
timezone
string

Timezone identifier string

Example:
Europe/Tallinn
timezone_short
string

Timezone abbreviation

Example:
EEST
gmt
string

Difference to Greenwich time (GMT) in hours

Example:
+0300

Examples

{
    "timestamp": 1525436423,
    "date": "2018-05-04",
    "time": "15:20:23",
    "full_datetime": "2018-05-04T15:20:23+03:00",
    "timezone": "Europe/Tallinn",
    "timezone_short": "EEST",
    "gmt": "+0300"
}
Organizer
Object
id
integer
Example:
4
name
string
Example:
Organizer Company Name Ltd.

Examples

{
    "id": 4,
    "name": "Organizer Company Name Ltd."
}
Event
Object
id
integer required

ID of the event

Example:
10
title
string required

Title of the event

Example:
Happy event
starts_at
string

Date and time of the start of the event

Example:
2018-09-22 00:00:00
ends_at
string

Date and time of the ending of the event

Example:
2018-10-22 23:59:59
duration_string
string

A human readable event duration string

Example:
Sat 22. September - Mon 22. October 2018

Examples

{
    "id": 10,
    "title": "Happy event",
    "starts_at": "2018-09-22 00:00:00",
    "ends_at": "2018-10-22 23:59:59",
    "duration_string": "Sat 22. September - Mon 22. October 2018"
}
Ticket

Event ticket

Object
id
integer
Example:
87
event_id
integer
Example:
10
order_id
integer
Example:
43
code
string
Example:
4LO4A3T8IH
status
string
Example:
UNUSED
used_at
string

Date and time the ticket was validated at. Null if not validated

Example:
2018-03-01 15:35:11
created_at
string
Example:
2018-02-01 13:24:48
updated_at
string
Example:
2018-02-01 13:24:48
validated_by
integer nullable

ID of the user who validated the ticket

Example:
1
ip
string

IP address of the user who validated the ticket

Example:
192.168.1.2
contents_html
string

Ticket contents HTML, for displaying on scanner:

  • Ticket row quantity x Ticket type, between <h1> tags
  • Attendee-based Order custom field values, marked with ‘Display on scanner’, between <h2> tags

Or, in case of a third-party ticket (has only code, no order_id and no ticket_rows), appropriate translation.

Examples:
<h1>1 x Regular ticket</h1><h1>2 x Student ticket</h1><h2>John</h2><h2>Smith</h2><h1>Check ticket type and amount from ticket</h1>
nametag_html
string

Name tag HTML for sending to printer. Filled with Attendee-based Order custom fields values when Event’s nametag_html template has been entered.

Example:
<!DOCTYPE html><html><body><p>Name: John</p><p>Surname: Smith</p></body></html>
qty
integer

Total quantity of visitors on the Ticket (sum of all Ticket Row’s quantities).

Example:
3
show more

Examples

{
    "id": 87,
    "event_id": 10,
    "order_id": 43,
    "code": "4LO4A3T8IH",
    "status": "UNUSED",
    "used_at": "2018-03-01 15:35:11",
    "created_at": "2018-02-01 13:24:48",
    "updated_at": "2018-02-01 13:24:48",
    "validated_by": 1,
    "ip": "192.168.1.2",
    "contents_html": "<h1>Check ticket type and amount from ticket</h1>",
    "nametag_html": "<!DOCTYPE html><html><body><p>Name: John</p><p>Surname: Smith</p></body></html>",
    "qty": 3
}
Attendee

Registration data provided by the buyer or attendee. Each attribute-value pair corresponds to the actual custom form field defined via Fienta’s UI for the particular event. The data below is just example and does not apply to all events.

Object
mail
string
Example:
john@smidth.com
name
string
Example:
John Smidth
country
string
Example:
Sweden
Webhooks
About webhooks

Fienta has three webhooks which can be turned on by the event organiser on Settings > Integrations page.

These trigger on

Order completion

Triggers when a ticket is bought or attendee has registered to a free event.

Object
id
number

Unique id of the order.

Example:
1234
status
string

Order status. Has always value “COMPLETED” when order completion webhook is triggered.

Example:
COMPLETED
locale
string

Language in which the user made the purhase or registraion.

Example:
en
ref
string

Referrer which lead to the purchase or registration. Event organiser has to use ?ref parameter when referring to the event URL in Fienta for this to have value.

Example:
facebook
buyer
Object
email
string

Contact email address which was entered by the buyer or attendee.

Example:
john@smidth.com
phone
string

Contact phone number which was entered by the buyer or attendee.

Example:
081 3888 382
mailinglist_subscribe
boolean

Whether the buyer or attendee signed up for event organiser’s mailinglist.

payment
Object
time
string

Time of payment or registration completion.

Example:
2020-06-03T14:26:07+03:00
total
integer

Total amount paid in cents.

Example:
2000
vat_percent
integer

VAT percentage, inluded in total amount.

Example:
20
currency
string
Example:
EUR
tickets
Array

Array of tickets

Object
code
string

Ticket code, in most cases embeded in QR code.

Example:
W753PV85CP
rows
Array

Specific tickets within specific ticket code. In majority of cases, only one row is returned as one ticket code refers to one ticket type. However this is not the case for compound tickets.

Object
ticket_type
Object
id
string
Example:
48482
title
string
Example:
Regular ticket
qty
string

Quantity, usually has value of 1.

Example:
1
event
Object
id
integer
Example:
3834
title
string
Example:
Die Hard 2
url
string
Example:
https://fienta.com/en/die-hard
image_url
string

URL of event hero image, can be emtpy string.

Example:
https://fienta.com/uploads/3834.jpg
starts_at
string
Example:
2020-11-14T19:00:00+02:00
ends_at
string
Example:
2020-11-14T20:10:00+02:00
time_description
string

Additional notes about event time.

Example:
Doors open at 18:30
duration_string
string

Human friendly representaion of event date and time.

Example:
Sat 14. November 2020 at 19:00 - 20:10
venue
Object
name
string
Example:
Noblessner movie theatre
address
string
Example:
Oak street 3, London
country_code
string
Example:
uk
organizer
Object
name
string
Example:
Smidth Events Ltd
phone
string
Example:
081 38484 28484
email
string
Example:
john@smidthevents.com
show more

Examples

{
    "id": 1234,
    "status": "COMPLETED",
    "locale": "en",
    "ref": "facebook",
    "buyer": {
        "email": "john@smidth.com",
        "phone": "081 3888 382",
        "mailinglist_subscribe": true
    },
    "payment": {
        "time": "2020-06-03T14:26:07+03:00",
        "total": 2000,
        "vat_percent": 20,
        "currency": "EUR"
    },
    "tickets": [
        {
            "code": "W753PV85CP",
            "rows": [
                {
                    "ticket_type": {
                        "id": "48482",
                        "title": "Regular ticket",
                        "qty": "1"
                    }
                }
            ]
        }
    ],
    "event": {
        "id": 3834,
        "title": "Die Hard 2",
        "url": "https://fienta.com/en/die-hard",
        "image_url": "https://fienta.com/uploads/3834.jpg",
        "starts_at": "2020-11-14T19:00:00+02:00",
        "ends_at": "2020-11-14T20:10:00+02:00",
        "time_description": "Doors open at 18:30",
        "duration_string": "Sat 14. November 2020 at 19:00 - 20:10",
        "venue": {
            "name": "Noblessner movie theatre",
            "address": "Oak street 3, London",
            "country_code": "uk"
        },
        "organizer": {
            "name": "Smidth Events Ltd",
            "phone": "081 38484 28484",
            "email": "john@smidthevents.com"
        }
    }
}
show more
Submitting registration form

Triggers when registration form is submitted after initial purchase.

Object
ticket
Array

Array of tickets

Object
code
string

Ticket code, in most cases embeded in QR code.

Example:
W753PV85CP
rows
Array

Specific tickets within specific ticket code. In majority of cases, only one row is returned as one ticket code refers to one ticket type. However this is not the case for compound tickets.

Object
ticket_type
Object
id
string
Example:
48482
title
string
Example:
Regular ticket
qty
string

Quantity, usually has value of 1.

Example:
1
attendee
Attendee
event
Event

Examples

{
    "ticket": [
        {
            "code": "W753PV85CP",
            "rows": [
                {
                    "ticket_type": {
                        "id": "48482",
                        "title": "Regular ticket",
                        "qty": "1"
                    },
                    "attendee": {
                        "mail": "john@smidth.com",
                        "name": "John Smidth",
                        "country": "Sweden"
                    }
                }
            ],
            "event": {
                "id": 10,
                "title": "Happy event",
                "starts_at": "2018-09-22 00:00:00",
                "ends_at": "2018-10-22 23:59:59",
                "duration_string": "Sat 22. September - Mon 22. October 2018"
            }
        }
    ]
}
show more
Ticket validation

Triggers when a ticket status is marked as USED. This can be done using Fienta’s mobile app, over web interface or via an API call.

Object
code
string
Example:
0O1TVHPTMU
status
string
Example:
USED
validated_at
string
Example:
2020-06-03T14:24:55+03:00
rows
Array
Object
ticket_type
Object
ticket_type_id
integer
Example:
48482
title
string
Example:
Regular ticket
qty
integer
Example:
1
event
Object
id
integer
Example:
3834
title
string
Example:
Die Hard 2
url
string
Example:
https://fienta.com/en/die-hard
image_url
string

URL of event hero image, can be emtpy string.

Example:
https://fienta.com/uploads/3834.jpg
starts_at
string
Example:
2020-11-14T19:00:00+02:00
ends_at
string
Example:
2020-11-14T20:10:00+02:00
time_description
string

Additional notes about event time.

Example:
Doors open at 18:30
duration_string
string

Human friendly representaion of event date and time.

Example:
Sat 14. November 2020 at 19:00 - 20:10
venue
Object
name
string
Example:
Noblessner movie theatre
address
string
Example:
Oak street 3, London
country_code
string
Example:
uk
organizer
Object
name
string
Example:
Smidth Events Ltd
phone
string
Example:
081 38484 28484
email
string
Example:
john@smidthevents.com
order
Object
id
integer
Example:
1234
status
string
Example:
COMPLETED
locale
string

Language in which the user made the purhase or registraion.

Example:
en
ref
string

Referrer which lead to the purchase or registration. Event organiser has to use ?ref parameter when referring to the event URL in Fienta for this to have value.

Example:
facebook
buyer
Object
email
string
Example:
john@smidth.com
phone
string
Example:
081 3888 382
mailinglist_subscribe
boolean

Whether the buyer or attendee signed up for event organiser’s mailinglist.

show more

Examples

{
    "code": "0O1TVHPTMU",
    "status": "USED",
    "validated_at": "2020-06-03T14:24:55+03:00",
    "rows": [
        {
            "ticket_type": {
                "ticket_type_id": 360,
                "title": "Regular ticket",
                "qty": 1
            }
        }
    ],
    "event": {
        "id": 147,
        "title": "Conference \"Birth Words\"",
        "url": "https://fienta.com/en/sunnisonad",
        "image_url": "https://fienta.com/uploads/147.jpg",
        "starts_at": "2020-11-14T19:00:00+02:00",
        "ends_at": "2020-11-14T20:10:00+02:00",
        "time_description": "",
        "duration_string": "Sat 14. November 2020 at 19:00 - 20:10",
        "venue": {
            "name": "Noblessner",
            "address": "Tööstuse 48 Tallinn",
            "country_code": "ee"
        },
        "organizer": {
            "name": "Korraldaja nimi",
            "phone": "",
            "email": "test@testkorraldaja.ee"
        }
    },
    "order": {
        "id": 240784,
        "status": "COMPLETED",
        "locale": "en",
        "ref": "close",
        "buyer": {
            "email": "rene@fienta.com",
            "phone": "",
            "mailinglist_subscribe": true
        }
    }
}
show more