Getting Started with Member Portal APIs

by Wade Girard

August 26, 2021

We provide a member portal for group members to use with their group. The member portal is available both as a web application at a url that the group sets up, as well as through a mobile app that we have developed.

The member portal theme can be changed through your administration portals settings section to use the styling that your club prefers, and you can control what options your group members can have access to through the portal as well.

You can also develop your own portal by using the same API’s that we have developed for our portal. This document will describe the steps to authenticate a member login, and access the API’s. Note that an API key, as described in the Getting started with API integration is not required for using the member portal APIs.

Getting the tenant information

The first step in the portal development process is to get the information for the tenant that you want to authenticate a member with. To do this you need to make a request with the get_tenant action and the subdomain for the tenant you are interested in.

{
"action": "get_tenant",
"subdomain": <tenant_subdomain>
}

If the group is found this will return the tenant information record. You will need some of the information in this record for future calls. You can save this information somewhere so you do not need to make this API call every time.

Authenticating a Member

Looking up the member

Authenticating a member is a multi step process. The first step involves looking up the member. You do this with the lookup_member action

{
"action":"lookup_member",
"tenant": <tenant_id>,
"username": <member_email_address>
}

This will cause the system to look for a member with the exact same email address that you provide. If the member is found you will get back a successful JSON response with the member record. One of the most important keys in this response will be the “hasPassword” key. If this is false you will need to walk the member through the process of setting up a password. If the member already has a password you can go to the next step of validating the member password with their email address.

If the member was not found you will get back an error response

{
"member":null,
"redirect":null,
"success":false,
"errorMessage":"Unable to find user with email fake@nowhere.com"
}

Logging in the member

After you have confirmed that you have found the member through the lookup, and they have a password, you can ask them to provide the password to you and send a member_login action with the login information

{
"action":"member_login",
"password": <password>,
"tenant": <tenant_id>,
"username": <member_email_address>
}

If the password is invalid you will get back an error

{
"success":false,
"errorMessage":"Invalid Password"
}

If successful you will get back a success response with an X-Dart-Token in the response header. You need to store this token as it will serve as the member identity for all member portal API’s. The token is good for 24 hours, but for security we recommend you build in an inactivity timeout and sign out the member and delete the token if they leave the portal.

Setting up a password

If the member is found by the lookup but hasPassword is false, you will need to setup their password. This is done with the member_set_password action

{
"action":"member_set_password",
"tenant": <tenant_id>,
"username": <member_email_address>,
"password": <password>
}

Security starts with strong passwords and the weakest link in security is always poor passwords. We strongly recommend that you check the password before setting it to verify that it meets industry security standards, like a mixture of upper and lower case letters, at least one number, at least one special characters, and at least 8 characters in length. Note that this API will only work to establish a password for the first time. If the user has forgotten their password you will need to use the forgot password API to force a strong password to be generated and emailed to the member.

{
"action":"member_forgot_password",
"tenant": <tenant_id>,
"username":<member_email_address>
}

The forgot password action will fail if the member has never had a password setup, so make sure you do not expose forgot password functionality if the hasPassword flag is false on the member record response.

Conclusion

With the X-Dart-Token you will be able to make any of the portal API calls on behalf of the member. We may add multi-factor authentication to member logins, like we do for admin logins, and if we do that we will update this documentation and give you time to implement it in your code.

Member API

by Wade Girard

August 11, 2021

In the middletwin platform, members are the object types that contain contact information for individual members. If performing an action like sending a message or an email, you will need to provide a member id. Members have the following actions.

create_member

update_member

delete_member

get_member

get_all_members

get_matching_members

Contact Properties for create/update actions

Field	Required	Description
id	Update/Delete	long – The id of the member
fname	n	String – The members first name (64 max)
lname	n	String – The members last name (64 max)
address	n	String – The members street address (128 max)
city	n	String – The members city (64 max)
state	n	String – The members state (32 max)
zip	n	String – The members zip (16 max)
phone1	y	String – The members mobile number (24 max)
phone2	n	String – The members other number (24 max)
email_address	n	String – The members other number (128 max)
stopped	n	boolean – The members

get_all_members has an optional type parameter which defaults to json, but you can specify csv to get a csv response.

get_matching_members requires the search_term parameter. The search_term is a String and will be compared against the members name, city, state, and email address. Matching members will be returned in an array.

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.

Getting Started with Member Portal APIs

Getting the tenant information

Authenticating a Member

Looking up the member

Logging in the member

Setting up a password

Conclusion

Tags

get_all_tags

get_tags

get_matching_tags

create_tag

update_tag

delete_tag

get_tag_members

create_tag_member

delete_tag_member

Member API

Contact Properties for create/update actions

Getting started with API integration

Basics

Authentication

Requests

Responses

Actions

CRUD

Linking your bank account

Settings

Member Information

Payments

Membership Renewal

Email notifications

Change Password

Mobile app

Files

Activities

Social

Signing In