Endpoints

These endpoints are out of date, for now you should see the controller files for the latest. We have a plan to generate automated API documentation based on these files.

All non-GET endpoints can return 400 Bad Request

Possible error codes:

• Validation problem

• cant-update-contribution

  User's contribution can't be updated right now. This is usually because they have a payment which is about to come out so it can't be changed until after that has cleared.

• no-payment-source

  The user has no active payment source to use to update or create a contribution

Most endpoints can return 401 Unauthorized if the user isn't authorized correctly

/auth

Login and return a session cookie

POST /auth/login

Request Body

Name	Type	Description
email*	String
password*	String

204: No Content Successfully logged in (cookie set on response)

{
    // Response
}

401: Unauthorized Login unsuccessful

{
    // Response
}

Logout and clear the user's session

POST /auth/logout

204: No Content Logged out

{
    // Response
}

/contact

Fetch basic information about the user

GET /contact/:id

Path Parameters

Name	Type	Description
id*	String	The ID of the user (use "me" for logged in user)

200: OK

200: OK

Example response:

{
    "email": "[email protected]",
    "firstname": "First",
    "lastname": "Last",
    "profile": {
        "deliveryOptIn": true,
        "deliveryAddress": {
            "line1": "Line 1",
            "line2": "",
            "city": "Bristol",
            "postcode": "BS1 1AA"
        },
        "newsletterStatus": "subscribed"
    },
    "joined": "2020-01-01T01:01:01.000Z",
    "contributionPeriod": "monthly",
    "contributionAmount": 3,
    "roles": ["member", "admin"]
}

Fetch information about a user's contribution

GET /contact/:id/contribution

Path Parameters

Name	Type	Description
id*	String	The ID of the user (use "me" for logged in user)

200: OK

Example response for a user with an active GoCardless contribution

{
    "type": "GoCardless",
    "amount": 5,
    "period": "monthly",
    "paymentSource": {
        "type": "direct-debit",
        "bankName": "A BANK NAME",
        "accountHolderName": "A B SMITH",
        "accountNumberEnding": 51
    },
    "membershipStatus": "active",
    "membershipExpiryDate": "2020-01-05T00:00:00Z"
}

Example response for a user an an expiring GoCardless contribution

{
    "type": "GoCardless",
    "amount": 5,
    "period": "monthly",
    "cancellationDate": "2020-01-01T00:00:00Z",
    "membershipStatus": "expiring",
    "membershipExpiryDate": "2020-01-05T00:00:00Z"
}

Example response for a user with an expired GoCardless contribution

{
    "type": "GoCardless",
    "amount": 5,
    "period": "monthly",
    "cancellationDate": "2020-01-01T00:00:00Z",
    "membershipStatus": "expired",
    "membershipExpiryDate": "2020-01-05T00:00:00Z"
}

Example response for a user with a manual contribution

{
    "type": "Manual",
    "amount": 5,
    "period": "monthly",
    "membershipStatus": "active",
    "membershipExpiryDate": "2020-01-05T00:00:00Z"
}

Example response for user without a contribution

{
    "type": "None",
    "membershipStatus": "none"
}

Update contribution amount

PATCH /contact/:id/contribution

Path Parameters

Name	Type	Description
id*	String	The ID of the user (use "me" for logged in user)

Request Body

Name	Type	Description
amount*	Number	The contribution amount to update to
payFee*	Boolean	Whether to absorb the fee or not
prorate*	Boolean	Should the change be prorated (always set to false for now)

200: OK Same as /member/me/contribution

{
    // Response
}

Start a contribution

POST /contact/:id/contribution

Path Parameters

Name	Type	Description
id	String	The ID of the user (use "me" for logged in user)

Request Body

Name	Type	Description
amount*	Number
period*	Enum
payFee*	Boolean
completeUrl*	String	The URL to redirect the user to after creating a payment method if they don't have one.

200: OK Contains the URL you should redirect the user to so they can set a payment source (e.g. with GoCardless)

{
    "redirectUrl": "https://..."
}

Complete a start contribution flow

POST /contact/:id/contribution/complete

Path Parameters

Name	Type	Description
id*	String	The ID of the user (use "me" for logged in user)

Request Body

Name	Type	Description
redirectFlowId*	String	The redirect flow to complete

200: OK Same as /member/me/contribution

{
    // Response
}

Add/update the user's payment source

PUT /contact/:id/payment-source

Path Parameters

Name	Type	Description
id*	String	The ID of the user (use "me" for logged in user)

Request Body

Name	Type	Description
completeUrl*	String

200: OK Contains the URL you should redirect the user to so they can set a payment source (e.g. with GoCardless)

{
    "redirectUrl": "https://..."
}

Complete an add/update payment source flow

POST /member/:id/payment-source/complete

Path Parameters

Name	Type	Description
id*	String	The ID of the user (use "me" for logged in user)

Request Body

Name	Type	Description
redirectFlowId*	String	The redirect flow to complete

200: OK Same as /member/me/contribution

{
    // Response
}

/reset-password

Create a reset password flow

POST /reset-password

Request Body

Name	Type	Description
email*	String
resetUrl	String	The URL to send the user to to reset their password. The reset password ID will be appended.

204: No Content Always returns success, even if email doesn't exist for security reasons

{
    // Response
}

Reset a password for a given reset password flow

PUT /reset-password/:id

Path Parameters

Name	Type	Description
id*	String	Reset password ID

Request Body

Name	Type	Description
password*	String	New password

404: Not Found Reset password ID doesn't exist

{
    // Response
}

204: No Content Successfully reset password

{
    // Response
}

/signup

Start a signup flow

POST /signup

Request Body

Name	Type	Description
email*	String
password*	String
contribution.completeUrl*	URL	The URL to send the user back to. Only applicable to redirect flow payment types, but must still contain a valid URL even if it won't be used
contribution.paymentMethod*	Enum	One of 's_card', 's_sepa', 's_bacs', 'gc_direct-debit'
contribution.amount*	Number
contribution.period*	Enum	'monthly' or 'annually'
contribution.payFee*	Boolean	Whether the user has opted to absorb the fee or not
contribution.prorate*	Boolean	Set to false for signups
loginUrl	URL	The URL the user should be redirected to if they are an existing user who can login
setPasswordUrl	URL	The URL the user should be redirected to if they are an existing user who needs to set a password
confirmUrl	URL	The URL the user will be sent in their email confirmation email

200: OK

For Stripe payment methods (s_...) the response will contain a client secret, you should use this to create a Setup Intent. See the Stripe docs for details: https://stripe.com/docs/payments/setup-intents

{
  "clientSecret": "seti_xxxxxx_secret_xxxxxx"
}

For GoCardless payments (gc_direct-debit) the response will contain a URL to redirect the user to

{
  "redirectUrl": "https://pay.gocardles.com/xxxxx"
}

Complete a signup flow

POST /signup/complete

Request Body

Name	Type	Description
paymentFlowId*	String	A unique ID to complete the payment, this will either be a Setup Intent for Stripe or a Redirect Flow ID for GoCardless
firstname	String	The new user's firstname
lastname	String	The new user's lastname

200: OK

Confirm email of a signup fow

POST /signup/confirm-email

Request Body

Name	Type	Description
joinFlowId	String	Confirm the email address associated with the join flow ID

Reference signup flow