List members

GET/v0.1/merchants/{merchant_code}/members

Lists merchant members.

OAuth scopes: Requires one of: user.subaccounts, members.read.

Required permissions:

merchant_read

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes user.subaccountsmembers.read

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"

Query parameters

offsetinteger
minimum: 0default: 0
Offset of the first member to return.

Example: 0
limitinteger
minimum: 1maximum: 25default: 10
Maximum number of members to return.

Example: 10
scrollboolean
default: false
Indicates to skip count query.

Example: true
emailstring
Filter the returned members by email address prefix.

Example: "user"
idstring
format: uuid
Search for a member by user id.

Example: "245b2ead-85bf-45ff-856f-311a88a5d454"
statusstring
Options:"accepted""pending""expired""disabled""unknown"
Filter the returned members by the membership status.
rolesarray<string>
Filter the returned members by role.

Example: ["role_employee","role_accountant"]

Responses

200application/json

Returns a list of Member objects.

itemsarray<object>required
Show 10 properties
- idstringrequired
  ID of the member.
  
  Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- rolesarray<string>required
  User's roles.
  
  Example: ["role_admin"]
- permissionsarray<string>requireddeprecated
  User's permissions.
  
  Example: ["members_read","members_write","create_moto_payments","full_transaction_history_view","refund_transactions","create_referral","developer_settings_edit","developer_settings_access"]
- created_atstringrequired
  format: date-time
  The timestamp of when the member was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_atstringrequired
  format: date-time
  The timestamp of when the member was last updated.
  
  Example: "2023-01-20T15:16:17Z"
- statusstringrequired
  Options:"accepted""pending""expired""disabled""unknown"
  The status of the membership.
- userobject
  Information about the user associated with the membership.
  
  Show 10 properties
  idstringrequired
  Identifier for the End-User (also called Subject).
  
  Example: "44ca0f5b-813b-46e1-aee7-e6242010662e"
  typestringrequired
  Options:"user""managed_user""service_account""system_account"
  Type of the user account.
  
  Example: "user"
  emailstringrequired
  End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
  
  Example: "example@sumup.com"
  mfa_on_login_enabledbooleanrequired
  True if the user has enabled MFA on login.
  
  Example: true
  virtual_userbooleanrequireddeprecated
  True if the user is a virtual user (operator).
  
  Example: false
  service_account_userbooleanrequireddeprecated
  True if the user is a service account.
  
  Example: false
  disabled_atstring
  format: date-time
  Time when the user has been disabled. Applies only to virtual users (virtual_user: true).
  
  nicknamestring
  User's nickname. Used for display purposes only.
  
  Example: "Test User"
  picturestring
  format: uri
  URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
  
  Example: "https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png"
  classicobjectdeprecated
  Classic identifiers of the user.
  
  Show 1 property
  user_idintegerrequired
  minimum: 0maximum: 2147483647
- inviteobject
  Pending invitation for membership.
  
  Show 2 properties
  emailstringrequired
  format: email
  Email address of the invited user.
  
  Example: "boaty.mcboatface@sumup.com"
  expires_atstringrequired
  format: date-time
  Example: "2023-01-20T15:16:17Z"
- metadataobject
  Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.
  
  Example: {}
- attributesobject
  Object attributes that are modifiable only by SumUp applications.
  
  Example: {}
total_countinteger
Example: 3

404application/problem+json

Merchant not found.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

GET

Code sample

curl --request GET \
  --url https://api.sumup.com/v0.1/merchants/MK10CL2A/members \
  --header 'Authorization: Bearer <token>'

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.members.list(
    "MK10CL2A",
    {
      "offset": 0
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Members.ListAsync(
            "your-merchant-code",
            new MembersListOptions
            {
                Offset = 10,
                Limit = 10,
                Scroll = true,
                Email = "merchant@example.com",
                UserId = Guid.Parse("00000000-0000-0000-0000-000000000001"),
                Status = MembershipStatus.Accepted,
                Roles = Array.Empty<string>(),
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class ListMerchantMembersSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.members().list(
            "MK10CL2A"
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.members.list(
    "MK10CL2A",
    offset=0,
    limit=10,
    scroll=True,
    email="user",
    user_id="245b2ead-85bf-45ff-856f-311a88a5d454",
    status="accepted",
    roles=[
        "role_employee",
        "role_accountant",
    ],
)
print(result)

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$queryParams = new \SumUp\Services\MembersListParams();
$queryParams->offset = 0;
$queryParams->limit = 10;
$queryParams->scroll = true;
$queryParams->email = 'user';
$queryParams->userId = '245b2ead-85bf-45ff-856f-311a88a5d454';
$queryParams->status = 'accepted';
$queryParams->roles = [
    'role_employee',
    'role_accountant',
];

$result = $sumup->members()->list(
    'MK10CL2A',
    $queryParams,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Members.List(context.TODO(), "MK10CL2A", sumup.MembersListParams{
		Offset: new(0),
		Limit:  new(10),
		Scroll: new(true),
		Email:  new("user"),
		UserID: new("245b2ead-85bf-45ff-856f-311a88a5d454"),
		Status: new(sumup.MembershipStatus("accepted")),
		Roles:  []string{"role_employee", "role_accountant"},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let response = client
        .members()
        .list("MERCHANT_CODE", sumup::resources::members::ListParams::builder().build())
        .await
        .expect("list request failed");
    println!("{response:#?}");
}

Response example

{
  "items": [
    {
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "roles": [
        "role_admin",
        "role_owner"
      ],
      "permissions": [
        "members_read",
        "members_write",
        "create_moto_payments",
        "full_transaction_history_view",
        "refund_transactions",
        "create_referral",
        "developer_settings_edit",
        "developer_settings_access"
      ],
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-02-20T15:16:17Z",
      "user": {
        "id": "44ca0f5b-813b-46e1-aee7-e6242010662e",
        "email": "example@sumup.com",
        "mfa_on_login_enabled": true,
        "virtual_user": false,
        "service_account_user": false
      },
      "status": "accepted"
    }
  ],
  "total_count": 3
}

{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you."
}