Skip to content

REST API v1

Jump to bottom
Celestino Bellone edited this page Dec 4, 2022 · 44 revisions

While we're working on exposing all Alf.io functionalities through APIs (this will happen in v2) we decided to develop a very simple API for creating / updating / deleting and retrieving event statistics.

Organization-level APIs

Event

Reservation

Subscription Descriptor

System-level APIs

Credits

Authentication

You must specify an API Client ApiKey in order to call the APIs.

curl -X POST  http://localhost:8080/api/v1/admin/event/create \
-H "Authorization: ApiKey e210468a-1831-4cf2-93d8-8cc093c7bd7d" \
-H "Cache-Control: no-cache" -H "Content-Type: application/json" \
-d "REQUEST_BODY_JSON (see below)"

ApiKey can be:

  • A system API Key for system-level requests (i.e. create a new organization)
  • An organization-level API Key for creating events and creating reservations

Organization-level requests

You can create an organization-level API Key from your Alf.io instance. Select "API Key" from the top menu and then fill in the details.

Create API Key

System-level requests

Only the "admin" user can view and rotate the System API Key. Select "API Key" from the top menu. You'll see

Create System API Key

Organization-level APIs

in order to consume this APIs you must generate a Organization-level API Key

Create Event

Request

POST /api/v1/admin/event/create

Sample Body (Reference)

{
    "title": "Titolo",
    "slug": "titolo",
    "description": [{
        "lang": "de",
        "body": "text description"
    }],
    "location": {
        "fullAddress": "Pollegio 6742 Switzerland",
        "coordinate": {
            "latitude": "45.55",
            "longitude": "9.00"
        }
    },
    "timezone": "Europe/Zurich",
    "startDate": "2018-08-12T08:00:00",
    "endDate": "2018-08-12T09:00:00",
    "websiteUrl": "http://www.amicidelticino.ch/aktivitaten/exklusivbesuch-des-kommandoturms-der-sbb",
    "termsAndConditionsUrl": "http://www.amicidelticino.ch/agb",
    "imageUrl": "https://www.amicidelticino.ch/assets/adt/images/amicidelticino-logo.png",
    "tickets": {
        "freeOfCharge": false,
        "max": 10,
        "currency": "CHF",
        "taxPercentage": 7.7,
        "taxIncludedInPrice": true,
        "paymentMethods": ["ON_SITE"],
        "categories": [
            {
                "name":"Standard",
                "description": [{
                    "lang": "de",
                    "body": "text description"
                }],
                "maxTickets": null,
                "accessRestricted": false,
                "price": 10.0,
                "startSellingDate": "2018-08-02T15:24:22",
                "endSellingDate": "2018-08-12T07:00:00",
                "groupLink": {
                   "groupId": 123,
                   "type": "LIMITED_QUANTITY",
                   "matchType": "EMAIL_DOMAIN",
                   "maxAllocation": 2
                }
            }
        ]
    },
    "extensionSettings": [{
        "extensionId": "mailchimp",
        "key":"listId",
        "value":"your-list-id"
    }]
}

Response

  • HTTP 200 {slug} - the given slug or a new, auto-generated one
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Update Event

Request

POST /api/v1/admin/event/update/{slug}

Sample Body (Reference)

{
    "title": "NewTitle",
    "startDate": "2018-08-12T08:01:00"
}

Response

  • HTTP 200 {slug}
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

List Subscriptions linked to Event

Request

GET /api/v1/admin/event/{slug}/subscriptions

Response

Link Subscriptions to Event

Request

PUT /api/v1/admin/event/{slug}/subscriptions

Sample Body

[
  "33bd5a7b-5bbf-4040-818b-c7e4c7490312"
]

Response

Generate tickets for subscribers

Triggers ticket generation for subscription holders linked to a given event

Request

POST /api/v1/admin/event/{slug}/generate-subscribers-tickets

Sample Body

{}

Response

  • HTTP 200 true if generation job has been scheduled
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Delete Event

Request

DELETE /api/v1/admin/event/{slug}

Response

  • HTTP 200 OK
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Create Reservation

POST /api/v1/admin/event/{slug}/reservation

Sample Body (Reference)

{
  "tickets": [
    {
      "ticketCategoryId": 53,
      "quantity": "1",
      "metadata": [{
        "attributeForTicket1": "value"
      }]
    },
    {
      "ticketCategoryId": 56,
      "quantity": "2",
      "metadata": [{
        "attributeForTicket1": "value1"
      }, {
        "attributeForTicket2": "value2"
      }]
    }
  ],
  "additionalServices": [
    {
      "additionalServiceId": 1,
      "quantity": 1
    }
  ],
  "promoCode": null,
  "user": {
    "username": "test@example.org",
    "firstName": "Test",
    "lastName": "McTest",
    "email": "test@example.org",
    "id": "external-id"
  },
  "configuration": {
     "hideContactData": false
  }
}

Response

  • HTTP 201 
    {
  "success": true,
  "id": "reservation-id",
  "href": "public-url-for-reservation",
  "errors": null
}
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Create Subscription Descriptor

Request

POST /api/v1/admin/subscription/create

Sample Body (SubscriptionDescriptorModificationRequest)

{
  "usageType": "ONCE_PER_EVENT",
  "termType": "standard",
  "term": {
    "timeUnit": "MONTHS",
    "units": 1
  },
  "title": [
    {
      "lang": "en",
      "body": "this is the title"
    }
  ],
  "description": [
    {
      "lang": "en",
      "body": "this is the description"
    }
  ],
  "onSaleFrom": "2022-07-23T12:00:18.22831",
  "onSaleTo": "2022-12-23T12:00:18.22831",
  "price": "10.00",
  "taxPercentage": "7.7",
  "taxPolicy": "INCLUDED",
  "currencyCode": "CHF",
  "imageUrl": "https://alf.io/img/tutorials/check-in-app/003.png",
  "termsAndConditionsUrl": "https://alf.io",
  "privacyPolicyUrl": "https://alf.io",
  "timezone": "Europe/Zurich",
  "supportsTicketsGeneration": false,
  "paymentMethods": [
    "STRIPE"
  ],
  "isPublic": true
}

Response

  • HTTP 200 {ID} - the subscription descriptor auto-generated ID (UUID)
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Update Subscription Descriptor

Request

POST /api/v1/admin/subscription/{id}/update

Sample Body (SubscriptionDescriptorModificationRequest)

{
  "usageType": "ONCE_PER_EVENT",
  "termType": "standard",
  "term": {
    "timeUnit": "MONTHS",
    "units": 1
  },
  "title": [
    {
      "lang": "en",
      "body": "this is the title"
    }
  ],
  "description": [
    {
      "lang": "en",
      "body": "this is the description"
    }
  ],
  "onSaleFrom": "2022-07-23T12:00:18.22831",
  "onSaleTo": "2022-12-23T12:00:18.22831",
  "price": "10.00",
  "taxPercentage": "7.7",
  "taxPolicy": "INCLUDED",
  "currencyCode": "CHF",
  "imageUrl": "https://alf.io/img/tutorials/check-in-app/003.png",
  "termsAndConditionsUrl": "https://alf.io",
  "privacyPolicyUrl": "https://alf.io",
  "timezone": "Europe/Zurich",
  "supportsTicketsGeneration": false,
  "paymentMethods": [
    "STRIPE"
  ],
  "isPublic": true
}

Response

  • HTTP 200 {ID}
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Get Subscription Descriptor

GET /api/v1/admin/subscription/{id}

Response

Get Linked Events

Returns events linked with a given Subscription Descriptor

GET /api/v1/admin/subscription/{id}/events

Response

  • HTTP 200 Array of Event Slugs
  • HTTP 404 Not found
  • HTTP 500 Error descriptor

Update Linked Events

Updates linked Events for a given Subscription Descriptor

Request

POST /api/v1/admin/subscription/{id}/events

Sample Body

[
  "event_1",
  "event_2"
]

Response

  • HTTP 200 Array of Event Slugs
  • HTTP 404 Not found
  • HTTP 500 Error descriptor

Deactivate Subscription Descriptor

Deactivates a given Subscription Descriptor. This will prevent people from using purchased subscriptions and from purchasing new ones of the same kind.

Request

DELETE /api/v1/admin/subscription/{id}/deactivate

Response

  • HTTP 200 Subscription Descriptor has been deactivated
  • HTTP 404 Not found
  • HTTP 500 Error descriptor

JSON Reference

Event Request

Name Description Mandatory
title The event name *
slug Short name, used in URLs
description Array of i18n, Markdown-formatted descriptions *
description.lang Language code *
description.body Localized, Markdown formatted, text *
location Event Location *
location.fullAddress Location address *
location.coordinate geolocation data: latitude and longitude *
timezone time zone identifier (e.g. Europe/Zurich, see List of tz database time zones) *
startDate start date/time, format: YYYY-MM-DDTHH:mm:SS *
endDate start date/time, format: YYYY-MM-DDTHH:mm:SS *
websiteUrl The URL of the event website (can be a dedicated page, or a generic website) *
termsAndConditionsUrl T&C URL *
privacyPolicyUrl Privacy Policy URL
imageUrl URL for retrieving the Event Logo. Must be accessible from alf.io's server *
tickets ticket categories definition *
tickets.freeOfCharge whether or not the event is free of charge *
tickets.max the maximum allowed seats *
tickets.currency ISO 4217 currency code (e.g. CHF, EUR, USD) if freeOfCharge is false
tickets.taxPercentage VAT/GST percentage if freeOfCharge is false
tickets.taxIncludedInPrice Whether the prices are already VAT/GST inclusive if freeOfCharge is false
tickets.paymentMethods Allowed Payment methods if freeOfCharge is false
tickets.categories Available ticket categories *
tickets.categories[n].name Name *
tickets.categories[n].description i18n Localized descriptions
tickets.categories[n].maxTickets Maximum tickets to allocate for this category
tickets.categories[n].accessRestricted Make the category private and generate unique access codes for it. Requires maxTickets > 0
tickets.categories[n].price Ticket price for this category if tickets.freeOfCharge is false
tickets.categories[n].startSellingDate Start Selling Date/Time *
tickets.categories[n].endSellingDate End Selling Date/Time *
tickets.categories[n].groupLink Tickets for this category can only be assigned to people in the given Group
tickets.categories[n].groupLink.groupId Group ID *
tickets.categories[n].groupLink.type Link type *
tickets.categories[n].groupLink.matchType Matching type *
tickets.categories[n].groupLink.maxAllocation max tickets allowed per match if matchType is "LIMITED_QUANTITY"
extensionSettings settings for extensions
extensionSettings.extensionId the id as defined in the Repository *
extensionSettings.key extension setting key *
extensionSettings.value extension setting value *

Create Reservation Request

Name Description Mandatory
reservation Tickets to reserve *
reservation.*.ticketCategoryId Category ID *
reservation.*.quantity number of tickets for the given category ID *
additionalService additional items to reserve
additionalService.*.additionalServiceId additional service ID *
additionalService.*.quantity number of additional services items *
promoCode promoCode to apply
user authenticated user who is performing the reservation
user.username username. Depending on the Authentication system in use, can be the user email *
user.firstName First name *
user.lastName Last name *
user.email Email *
user.id External ID, this attribute is currently ignored
configuration reservation process configuration
configuration.hideContactData whether to hide the "contact data" section. Useful if user was specified

System-level APIs

List Organizations

GET /api/v1/admin/system/organization/list

Response

Get Organization

GET /api/v1/admin/system/organization/{id}

Response

  • HTTP 200 Organization
  • HTTP 404 Organization ID not found
  • HTTP 500 Error descriptor

Create Organization

Request

POST /api/v1/admin/system/organization/create

Sample Body (OrganizationModification)

{
    "name": "New Organization",
    "email": "info@example.org",
    "description": "mandatory description"
}

Response

  • HTTP 200 Organization
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Update Organization

Request

POST /api/v1/admin/system/organization/{id}

Sample Body (OrganizationModification)

{
    "id": 1,
    "name": "New Name",
    "email": "info@example.org",
    "description": "mandatory description"
}

Response

  • HTTP 200 Organization
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Delete Organization

DELETE /api/v1/admin/system/organization/{id}

Warning This will delete all Events, Subscriptions, Reservations owned by the Organization you're deleting

Response

  • HTTP 200 OK
  • HTTP 400 Error descriptor
  • HTTP 500 Error descriptor

Create API Key for Organization

PUT /api/v1/admin/system/organization/{id}/api-key

Response

  • HTTP 200 OrganizationApiKey { "organizationId": 123, "apiKey": "abcd" }
  • HTTP 500 Error descriptor

Credits

We would like to thank

Starplane

for sponsoring the development of this feature. Thank you!

Clone this wiki locally