Create a member

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

Adds a member to the merchant account with the specified roles.

By default, sends an invitation email to the provided address. The recipient must accept the invitation to join the account. When is_managed_user is true, creates a managed user with the provided password and optional nickname and assigns the roles directly, without sending an invitation.

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

Required permissions:

members_create

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes user.subaccountsmembers.write

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"

Body parameters

application/jsonrequired

emailstringrequired
format: emailmaxLength: 256
Email address of the member to add.
rolesarray<string>required
maxLength: 64
List of roles to assign to the new member.
is_managed_userboolean
True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname.
passwordstring
format: passwordminLength: 8
Password of the member to add. Only used if is_managed_user is true. In the case of service accounts, the password is not used and can not be defined by the caller.
nicknamestring
maxLength: 64
Nickname of the member to add. Only used if is_managed_user is true. Used for display purposes only.

Example: "Test User"
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: {}

Responses

201application/json

Returns the Member object if the creation succeeded.

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: {}

400application/problem+json

Invalid request.

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.

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.

429application/problem+json

Too many invitations were sent to that user and the rate limit was exceeded. The Retry-After header indicates when the client can retry.

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.

Code sample

curl --request POST \
  --url https://api.sumup.com/v0.1/merchants/MK10CL2A/members \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "karl.berg@example.com",
  "roles": [
    "role_employee"
  ]
}
'

import SumUp from "@sumup/sdk";

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

  const result = await client.members.create(
    "MK10CL2A",
    {
      "email": "karl.berg@example.com",
      "roles": [
        "role_employee"
      ]
    }
  );
  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.CreateAsync(
            "your-merchant-code",
            new MembersCreateRequest
            {
                Email = "karl.berg@example.com",
                Roles = new string[]
                {
                    "role_employee",
                },
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.members().create(
            "MK10CL2A",
            com.sumup.sdk.models.CreateMerchantMemberRequest.builder()
                .email("karl.berg@example.com")
                .roles(java.util.List.of("role_employee"))
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.members.create(
    "MK10CL2A",
    email="karl.berg@example.com",
    roles=[
        "role_employee",
    ],
)
print(result)

<?php

declare(strict_types=1);

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

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

$body = [
    'email' => 'karl.berg@example.com',
    'roles' => [
        'role_employee',
    ],
];

$result = $sumup->members()->create(
    'MK10CL2A',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Members.Create(context.TODO(), "MK10CL2A", sumup.MembersCreateParams{
		Email: "karl.berg@example.com",
		Roles: []string{"role_employee"},
	})
	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 body = sumup::resources::members::CreateRequest::builder()
        .email("karl.berg@example.com")
        .roles(vec!["role_employee".to_string()])
        .build();
    let response = client
        .members()
        .create("MERCHANT_CODE", body)
        .await
        .expect("create request failed");
    println!("{response:#?}");
}

Response example

{
  "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"
}

{
  "type": "https://developer.sumup.com/problem/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed."
}

{
  "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."
}

{
  "type": "https://developer.sumup.com/problem/too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests were sent. Please try again later."
}