Getting started with API integration

by Wade Girard

August 11, 2021

Welcome to the API for the middletwin platform. With the API you are able to execute various functions within your account on the middletwin platform.

Basics

All calls into the API need to be POST requests. Each API call needs to have the proper X header parameters for authentication (see below), and have a JSON formatted body (unless noted otherwise). All responses from our server will be in JSON format, we do not support XML or any other formats at this time. All JSON responses will have a success key with a boolean value indicating of the request was successful, and an errorMessage key that will have a string value if success is not true.

Authentication

To get started, you will need to obtain a set of API keys for the account that you want to use. Our API security requires a key pair to make API calls. One of the keys is a PUBLIC key, meaning we store it in our database and use it as a lookup for the account that you are accessing. The second key is a SECRET key. This key is not stored in our system, it is generated at the time the key is created, and is only visible at that time.

You will need this key pair before you can begin, and you will need to store them in a safe place.

The PUBLIC and SECRET key pair must be provided with every API call that you make as X headers in the request.

X-Apikey=<PUBLIC KEY>
X-SecretKey=<SECRET KEY>

If these keys are invalid or attempt to make a request to a resource that they do not have access to, you will receive a 401 response.

Requests

All requests are POST requests to the following URL:

https://app.middletwin.com/dart/core

The JSON body of the request has an ‘action’ attribute that dictates the action you would like to perform and any other parameters (required or optional) to support the request.

‘object types’ that list the actions.

Example
{
   "action":"get_all_members",
   "limit":"25",
   "offset":"0",
   "orderby":"lname",
   "nostatus":"true"
}

Responses

All responses will be in JSON and will have a success key with a boolean value and an errorMessage key with a string value.

Example
{
    "success":true,
    "errorMessage":"",
    "limit":"25",
    "offset":"0",
    "members":[...]
}

Actions

Actions are dependent on the permissions that your keys have access to. Key permissions are just like user permissions, and an API with a key pair is treated like a user with access to the account.

CRUD

Almost all resources in the middletwin platform have actions for basic CRUD functionality (Create, Read, Update, Delete). Most of the actions will be of the form create_<objecttype>, update_<objecttime>, etc… Create actions will almost always return with the id of the newly created object. Update and Delete will almost always require the id of the object you want to update or delete. In most cases, read operations (get) will respond with the entire object record. For some object types, the read operations that return multiple records are paginated.

Linking your bank account

by Wade Girard

July 29, 2021

In order for your group members to be able to purchase memberships or club merchandise, you will need to have your clubs bank account linked to your Middletwin account. Middletwin uses Stripe to handle payment processing. To prepare yourself for doing this you will want to have the following information available and ready while you are setting this up.

Your groups address and phone number
Your groups tax id number (aka EIN)
Login access to your groups banking

An administrator with Account Admin privilege will have to set this up as this setup is limited to only logins with the highest level of privileges.

To go the finance settings by clicking on the “Finance” tab and then select the “Bank Link” icon within the summary section.

You should see a Stripe Account Id. This is an account that Middletwin automatically created for your group when your account was created. If this field is blank please contact Middletwin support before preceding and ask that a Stripe account be created for your group. Also, if you already have an account with Stripe and you would prefer to use your existing account, please contact Middletwin support.

If you do not see your bank and the last for digits of your bank account number under the “Linked Bank Accounts” label, click the ‘Link Bank Account’ button to be re-directed to strip to link a bank account.

It is important to know that Middletwin, at no time, will have your bank account Information, only Stripe does.

The Email should be filled in with your email address. At this point you are going to begin the process of filling in all the Information that Stripe will require in order for them to active the link from Stripe to your account, which will allow all online credit card transaction to go directly into your bank account. Make note of the login information that you setup in Stripe as you can use it to access the Stripe account directly and see the transactions, refund customers, and do many other actions.

When you are finished you will be directed back to the Middletwin login screen. Login and go back to the Billing/Subscription view and instead of seeing “None, click the ‘Link Bank Account’ button to link a bank account” you should see your bank name and the last 4 digits of your bank account. This is an indication that everything is properly setup. If you have any difficulties while on the Middletwin portal, contact Middletwin support, if you have any issues while on the Stripe setup pages, please contact Stripe support, they are very helpful. You can tell which site you are on by looking at the URL.

Settings

by Wade Girard

April 18, 2021

The settings tab allows members to manage various settings for their membership and notifications.

Member Information

The member information section shows information about the membership like when the membership began and what the members id is. This is just for reference and the member is not able to change this information.

Payments

In the payments section the member can manage their own credit card. Note that Middletwin DOES NOT store credit card information. Middletwin uses a service called Braintree, which is a PayPal company, to manage credit cards, payments, refunds, and all credit card related processes.

A member can choose to add a payment method as a convenience so that they can setup automatic membership renewals and easily purchase club merchandise or register for events without having to enter in their payment method every time.

This section will also show the payment history for the member.

Membership Renewal

Members can actively add to their membership by clicking the “Renew now” button, this will add 1 year to their membership or they can passively have their membership renew by providing a payment method and clicking the checkbox to enable automatic renew. Emails will be sent when the membership is renewed.

Email notifications

Members can control what they want to receive email notifications for.

Change Password

Members can change their password from the settings tab.

Mobile app

Links and instructions to download the member portal mobile app for Apple iPhone and Google Android devices. See the dedicated knowledge base documents for the mobile app if you need help with using the app.

Files

by Wade Girard

April 18, 2021

On the files tab members can access files that the group membership administrator has uploaded and chosen to share with members. Note that members cannot upload files, this is only for the group to share files. This is typically used to share newsletters or other appropriate content.

The files will be ordered from most recent to oldest upload date.

Activities

by Wade Girard

April 18, 2021

The activities tab in the member portal allows members to view upcoming activities that are managed by the group membership administrator. Activities are viewed by month/year.

Members can use the control in the upper right corner to toggle to future and past months to view the groups activities.

Social

by Wade Girard

April 18, 2021

The social tab is a dedicated social area for group members to interact with each other. Members can create posts of what they are doing that is group related as well as react and comment on other members posts.

Note that by using the member portal members are expected to adhere to the Middletwin terms of use and not post content that is inappropriate or copyrighted.

For creating a post or a comment to a post the member can enter in up to 1024 characters of text, and up to 10 photos.

Signing In

by Wade Girard

April 18, 2021

The group member portal uses a unique URL that is specific to the group. In order for group members to access the portal they must use the correct URL. The URL uses the patters https://<group subdomain>.middletwin.com/. The group subdomain is configured by an administrator with the Account Administrator permission. Once set, the subdomain cannot be changed.

You should advertise this URL on your groups public presence.

The member portal has 2 main states, public view and member view. When the portal loads it will be in the public view.

The differences are that the link in the upper right corner says “Sign In” and the group description is in the main portion of the portal instead of the tabs.

Members sign in by clicking the “Sign In” link in the top right corner. Note that non members can join the group by clicking the “Join” link, and if you have events that allow for registration they will be listed when the visitor clicks the “Events” link.

When signing in the member uses their email address that is associated with their membership. This is checked, if the email address is not found in the groups membership, they will get an error

If the email address lookup succeeds the login process will check to see if this is the first time the member has logged in. If it is they will be guided through the steps to create a password, if not they will be asked to provide their password.

If a member forgets their password they can use the “Forgot Password” button to have a temporary password generated and emailed to them.

Returns

by Wade Girard

March 30, 2021

Handling returns is just a part of doing business. Because your club is being hosted on Middletwin you will need to have your own returns policy. This is required in order to maintain compliance with our payment processor, Stripe, as well as the major credit card providers.

We have a group returns polity that your group uses by default if you do not provide your own return policy. Acceptance of this return policy is a part of our terms of use that you agree to when signing up to use Middletwin.

The default return policy

Membership Fees

All membership fees are non-refundable. If a member wishes to discontinue their membership with your group you can choose if you want to allow them to maintain their membership until it expires, however all membership dues are non-refundable.

If a membership is cancelled by the group for any reason, the membership fees paid by the outgoing member are non-refundable.

Exceptions to the membership fees return policy can be made by the group providing to Middletwin support a copy of the groups adopted membership return policy. The group can issue refunds as it sees fit through the groups own devices at the groups discretion (ex mailing a check). The group may have Middletwin issue a credit card refund by contacting Middletwin support. There will be a $10 fee per refund for this service.

Store Merchandise

All store merchandise can be returned and the group accepting the return must issue a refund through its own mechanism within 24 hours of receipt of merchandise. The group may apply any restocking fees as deemed appropriate by the group if the revoking fee is disclosed in the merchandise listing. The group may make exceptions to this by explicitly providing the customer with a written instrument of the exceptions directly in the merchandise listing.

All store merchandise can be exchanged and the group accepting the exchange must send the replacement to the customer within 24 hours of receipt of the merchandise being exchanged. The group my apply any restocking fees as deemed appropriate by the group if the revoking fee is disclosed in the merchandise listing. The group may make exceptions to this by explicitly providing the customer with a written instrument of the exceptions directly in the merchandise listing.

The group may have Middletwin issue a credit card refund by contacting Middletwin support. There will be a $10 fee per refund for this service.

Exceptions to this policy can be made by the group putting explicit policies in the merchandise listing.

Event Registrations

All online registrations are non-refundable. If an event registrant wishes to cancel their registration they may do so by contacting the group. If the group wishes to refund the registrant they can through their own process. The group may have Middletwin issue a credit card refund by contacting Middletwin support. There will be a $10 fee per refund for this service.

The group must have its own policies in place for refunds due to unforeseen circumstances like weather related cancellations.

Event Tickets

All online tickets are non-refundable. Events tickets become the property of the purchaser when purchased. They may resell them on their own. Neither Middletwin or the group will buy back event tickets.

Schedules

by Wade Girard

March 30, 2021

Schedules are a way to manage works schedules for events. The Schedules app is available to logins with the “Schedule Manager” permission.

When the schedules app initially load it will display the list of current schedules. A schedule consists of a descriptive name and a color for reference.

To create a schedule click on the “Add schedule” button above the table on the right side.

Enter a descriptive name and a color. You can use valid hex color values or html color names. Google html colors for more information. Click “Save” when finished.

This will add a new schedule to the list of schedules. Click on a schedule to edit a schedule and add shifts.

Shifts

All schedules need to have shifts. To manage shifts you need to go into the schedule details by click on the row for a schedule (not the checkbox in the leftmost column). In right side pane of the schedule details you will see the list of shifts for the schedule.

To Add a shift click on the “Add shift” button above the table on the right.

In the shift dialog you will specify the quantity of shifts to create, the date of the shifts, the start hour and start minute, and duration of the shifts. Click “Save” when you are finished.

To edit a shift click on the row for the shift (not the checkbox in the leftmost column) and the shift dialog will open with the shift details. To delete a shift select the checkbox in the leftmost column of the shift you want to delete and a trash can icon will appear above the table on the right side. Click the trash can icon to delete the shift.

Workers

Workers need to be defined in order to assign workers to shifts. To manage workers go to the schedules app and select the “Workers” tab.

The list of workers contains the worker information. To create a worker click on the “Add worker” button above the table to the right

In the worker dialog you can specify the worker name, contact information, and shirt size. Click “Save” and the worker will be added to your list of workers.

To edit a worker click on the row for a worker (not the checkbox in the leftmost column) and the worker dialog will open with the worker information. To delete a worker select the checkbox in the leftmost column of the worker you want to delete and a trash can icon will appear above the table on the right side. Click the trash can icon to delete the worker.

Voting

by Wade Girard

March 30, 2021

If you use classes for your event, you will have the ability to have voting. Voting works by creating a ballot with all the classes on the ballot and a place to write in the registration number that someone wants to vote for. Once voting is completed and you have collected all the ballots you can have one or more people with an administrator login (can be the same login) that has the “Ballot Manager” permission enabled. This will allow the user to access the Ballot app.

When the ballot app loads it will display a list of the events in the system. Select the event row (not the checkbox in the left most column) to access the ballot for that event.

A panel will slide open on the right side of the view with the classes and a text box by each class

And at the bottom of the screen will be some floating buttons

Bloating buttons

Ballots can be easily entered by typing in the number for a class and hitting enter will bring the focus to the next class entry field. When done click the “Submit Ballot” button. Note that if you enter in a registration number that does not exists, the system will accept it without reporting any information about that. It is just ignored. The system is designed that way to allow for quick entry.

When done the person entering the ballots can click the “X” at the top or the “Back” button in the floating buttons to close the panel

Results

To see the voting results, someone with “Event Manager” permissions can go to the Events app, open the event details, and in the middle pane click on “Results”

The top 10 registrations in each class will be displayed with the number of votes and the first column, registration name, registration information and registration number.