List Persons

GET/v1/merchants/{merchant_code}/persons

Returns the Persons related to a Merchant.

OAuth scopes: Requires one of: user.profile, user.profile_readonly.

Required permissions:

persons_read

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes user.profileuser.profile_readonly

Authorization guide

Path parameters

merchant_codestringrequired
Short unique identifier for the merchant.

Example: "MK10CL2A"

Responses

200application/json

Returns a list of Persons for a valid Merchant identifier.

itemsarray<unknown>required
Show 16 properties
- idstringrequired
  The unique identifier for the Person. This is a typeid.
  
  Example: "pers_2EGQ057R6C8J791RVCG5NWAEAB"
- user_idstring
  A corresponding identity user ID for the Person, if they have a user account.
  
  Example: "ef263f37-8701-4181-9758-acddbb778ee9"
- birthdatestring
  format: date
  The date of birth of the individual, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format.
  
  Example: "1980-01-12"
- given_namestring
  minLength: 1maxLength: 60
  The first name(s) of the individual.
  
  Example: "James Herrald"
- family_namestring
  minLength: 1maxLength: 60
  The last name(s) of the individual.
  
  Example: "Bond"
- middle_namestring
  minLength: 1maxLength: 60
  Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.
  
  Example: "Maria Sophie"
- phone_numberstring
  maxLength: 16
  A publicly available phone number in E.164 format.
  
  Example: "+420123456789"
- relationshipsarray<string>
  A list of roles the Person has in the Merchant or towards SumUp. A Merchant must have at least one Person with the relationship representative.
- ownershipobject
  Details about the ownership relationship between the Person and the Merchant. This is only set if the Person has a relationship of type owner.
  
  Show 1 property
  shareintegerrequired
  format: int32minimum: 25000maximum: 100000
  The percent of ownership shares held by the Person expressed in percent mille (1/100000). Only Persons with the relationship owner can have ownership.
  
  Example: 50000
- addressobject
  An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.
  
  Example: {"street_address":["Paul-Linke-Ufer 39-40","2. Hinterhof"],"post_code":"10999","city":"Berlin","country":"DE"}
  Show 17 properties
  countrystringrequired
  minLength: 2maxLength: 2pattern: ^[A-Z]{2}$
  An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.
  
  Example: "BR"
  street_addressarray<string>
  maxLength: 100
  Example: ["Paul-Linke-Ufer 39-40","2. Hinterhof"]
  post_codestring
  maxLength: 10
  The postal code (aka. zip code) of the address.
  
  Example: "10999"
  citystring
  maxLength: 60
  The city of the address.
  
  Example: "Berlin"
  provincestring
  maxLength: 60
  The province where the address is located. This may not be relevant in some countries.
  
  Example: "Berlin"
  regionstring
  maxLength: 60
  The region where the address is located. This may not be relevant in some countries.
  
  Example: "Baden Wuerttemberg"
  countystring
  maxLength: 60
  A county is a geographic region of a country used for administrative or other purposes in some nations. Used in countries such as Ireland, Romania, etc.
  
  Example: "Dublin County"
  autonomous_communitystring
  maxLength: 60
  In Spain, an autonomous community is the first sub-national level of political and administrative division.
  
  Example: "Catalonia"
  post_townstring
  maxLength: 60
  A post town is a required part of all postal addresses in the United Kingdom and Ireland, and a basic unit of the postal delivery system.
  
  Example: "London"
  statestring
  maxLength: 60
  Most often, a country has a single state, with various administrative divisions. The term "state" is sometimes used to refer to the federated polities that make up the federation. Used in countries such as the United States and Brazil.
  
  Example: "California"
  neighborhoodstring
  maxLength: 60
  Locality level of the address. Used in countries such as Brazil or Chile.
  
  Example: "Copacabana"
  communestring
  maxLength: 60
  In many countries, terms cognate with "commune" are used, referring to the community living in the area and the common interest. Used in countries such as Chile.
  
  Example: "Providencia"
  departmentstring
  maxLength: 60
  A department (French: département, Spanish: departamento) is an administrative or political division in several countries. Used in countries such as Colombia.
  
  Example: "Antioquia"
  municipalitystring
  maxLength: 60
  A municipality is usually a single administrative division having corporate status and powers of self-government or jurisdiction as granted by national and regional laws to which it is subordinate. Used in countries such as Colombia.
  
  Example: "Medellín"
  districtstring
  maxLength: 60
  A district is a type of administrative division that in some countries is managed by the local government. Used in countries such as Portugal.
  
  Example: "Lisbon District"
  zip_codestring
  maxLength: 10
  A US system of postal codes used by the United States Postal Service (USPS).
  
  Example: "94103"
  eircodestring
  maxLength: 10
  A postal address in Ireland.
  
  Example: "D02 X285"
- identifiersarray<object>
  A list of country-specific personal identifiers.
  
  Example: [{"ref":"br.cpf","value":"847.060.136-90"}]
  Show 2 properties
  refstringrequired
  maxLength: 32
  The unique reference for the personal identifier type.
  
  Example: "br.cpf"
  valuestringrequired
  maxLength: 128
  The personal identifier value.
  
  Example: "847.060.136-90"
- citizenshipstring
  minLength: 2maxLength: 2pattern: ^[A-Z]{2}$
  An ISO3166-1 alpha-2 country code. This definition users oneOf with a two-character string type to allow for support of future countries in client code.
  
  Example: "BR"
- nationalitystringnullable
  pattern: ^[A-Z]{2}$
  The Person's nationality. May be an ISO3166-1 alpha-2 country code, but legacy data may not conform to this standard.
- country_of_residencestringnullable
  pattern: ^[A-Z]{2}$
  An ISO3166-1 alpha-2 country code representing the country where the Person resides.
- versionstring
  The version of the resource. The version reflects a specific change submitted to the API via one of the PATCH endpoints.
  
  Example: "chng_01HS0KG3MPVEVWW85E3KNXH55J"
- change_statusstring
  Reflects the status of changes submitted through the PATCH endpoints for the Merchant or Persons. If some changes have not been applied yet, the status will be pending. If all changes have been applied, the status done. The status is only returned after write operations or on read endpoints when the version query parameter is provided.

404application/problem+json

The requested Merchant does not exist.

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/v1/merchants/MK10CL2A/persons \
  --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.merchants.listPersons(
    "MK10CL2A"
  );
  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.Merchants.ListPersonsAsync(
            "your-merchant-code");

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

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

    var result = client.merchants().listPersons(
            "MK10CL2A"
        );
    System.out.println(result);
  }
}

<?php

declare(strict_types=1);

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

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

$result = $sumup->merchants()->listPersons(
    'MK10CL2A',
);

var_dump($result);

package main

import (
	"context"
	"fmt"

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

func main() {
	client := sumup.NewClient()
	result, err := client.Merchants.ListPersons(context.TODO(), "MK10CL2A")
	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
        .merchants()
        .list_persons("MERCHANT_CODE")
        .await
        .expect("list_persons request failed");
    println!("{response:#?}");
}

Response example

{
  "items": [
    {
      "id": "pers_2EGQ057R6C8J791RVCG5NWAEAB",
      "user_id": "ef263f37-8701-4181-9758-acddbb778ee9",
      "birthdate": "1980-01-12",
      "given_name": "James Herrald",
      "family_name": "Bond",
      "middle_name": "Maria Sophie",
      "phone_number": "+420123456789",
      "relationships": [
        "representative"
      ],
      "ownership": {
        "share": 50000
      },
      "address": {
        "street_address": [
          "Paul-Linke-Ufer 39-40",
          "2. Hinterhof"
        ],
        "post_code": "10999",
        "city": "Berlin",
        "country": "DE"
      },
      "identifiers": [
        {
          "ref": "br.cpf",
          "value": "847.060.136-90"
        }
      ],
      "citizenship": "BR",
      "nationality": "string",
      "country_of_residence": "string",
      "version": "chng_01HS0KG3MPVEVWW85E3KNXH55J",
      "change_status": "string"
    }
  ]
}

{
  "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.",
  "instance": "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"
}