# List clients Retrieve a list of all clients linked to your account. The results are paginated. > 🔑 Access with > > [Organization access token with **clients.read**](/reference/authentication) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Mollie Connect", "version": "1.0.0", "license": { "name": "Attribution-NonCommercial-ShareAlike 4.0 International", "identifier": "CC-BY-NC-SA-4.0" } }, "servers": [ { "url": "https://api.mollie.com" } ], "security": [ { "apiKey": [] }, { "organizationAccessToken": [] }, { "oAuth": [] } ], "paths": { "/v2/clients": { "get": { "summary": "List clients", "x-speakeasy-name-override": "list", "tags": [ "Clients API" ], "operationId": "list-clients", "security": [ { "organizationAccessToken": [ "clients.read" ] } ], "description": "Retrieve a list of all clients linked to your account.\n\nThe results are paginated.\n\n> 🔑 Access with\n>\n> [Organization access token with **clients.read**](/reference/authentication)", "parameters": [ { "description": "This endpoint allows embedding related API items by appending the following values via the `embed` query string parameter.\n\n* `organization`: Include the organization of the client. Available for `signuplink` partners, or for `oauth` partners with the `organizations.read` scope.\n* `onboarding`: Include the onboarding status of the client. Available for `signuplink` partners, or for `oauth` partners with the `onboarding.read` scope.\n* `capabilities`: Include the [capabilities](list-capabilities) of the client organization. Available for *oauth* partners with the `onboarding.read` scope.", "schema": { "type": [ "string", "null" ], "example": "organization" }, "name": "embed", "in": "query" }, { "schema": { "type": "string", "example": "org_12345678" }, "name": "from", "description": "Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.", "in": "query" }, { "name": "limit", "description": "The maximum number of items to return. Defaults to 50 items.", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 250, "default": 50, "example": 50 } } ], "responses": { "200": { "description": "A list of client objects. For a complete reference of the client object, refer to the [Get client endpoint](get-client) documentation.", "content": { "application/hal+json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of items in this result set. If more items are available, a `_links.next` URL will be present in the result as well.\n\nThe maximum number of items per result set is controlled by the `limit` property provided in the request. The default limit is 50 items.", "minimum": 1, "maximum": 250, "example": 5 }, "_embedded": { "type": "object", "properties": { "clients": { "description": "An array of client objects. For a complete reference of the client object, refer to the [Get client endpoint](get-client) documentation.", "type": "array", "items": { "allOf": [ { "type": "object", "required": [ "resource", "id", "_links" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains a client object. Will always contain the string `client` for this resource type.", "readOnly": true, "default": "client" }, "id": { "allOf": [ { "type": "string", "pattern": "^org_.+$", "example": "org_1234567" } ], "description": "The identifier uniquely referring to this client. Example: `org_12345678`.", "readOnly": true }, "commission": { "type": [ "object", "null" ], "description": "The commission object.", "properties": { "count": { "type": "integer", "description": "The commission count.", "example": 10 } } }, "organizationCreatedAt": { "type": "string", "description": "The date and time the client organization was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "readOnly": true, "example": "2023-01-15T13:45:30+00:00" }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "required": [ "self" ], "properties": { "self": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "organization": { "description": "The API resource URL of the client's organization.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "onboarding": { "description": "The API resource URL of the client's onboarding status.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } }, { "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "organization": { "type": "object", "required": [ "resource", "id", "name", "email", "locale", "address", "registrationNumber", "_links" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains an organization object. Will always contain the string `organization` for this resource type.", "readOnly": true, "default": "organization" }, "id": { "allOf": [ { "type": "string", "pattern": "^org_.+$", "example": "org_1234567" } ], "readOnly": true }, "name": { "type": "string", "description": "The name of the organization.", "example": "My Online Store", "readOnly": true }, "email": { "type": "string", "description": "The email address associated with the organization.", "example": "example@mail.com", "readOnly": true }, "locale": { "type": "string", "allOf": [ { "type": [ "string", "null" ], "description": "Allows you to preset the language to be used.\n\nPossible values: `en_US` `en_GB` `nl_NL` `nl_BE` `de_DE` `de_AT` `de_CH` `fr_FR` `fr_BE` `es_ES` `ca_ES` `pt_PT` `it_IT` `nb_NO` `sv_SE` `fi_FI` `da_DK` `is_IS` `hu_HU` `pl_PL` `lv_LV` `lt_LT` `null`", "example": "en_US" } ], "description": "The preferred locale of the merchant, as set in their Mollie dashboard.", "readOnly": true }, "address": { "description": "The address of the organization.", "type": "object", "required": [ "streetAndNumber", "postalCode", "city", "country" ], "properties": { "streetAndNumber": { "type": "string", "description": "A street and street number.", "example": "Keizersgracht 126" }, "postalCode": { "type": "string", "description": "A postal code. This field may be required if the provided country has a postal code system.", "example": "1015 CW" }, "city": { "type": "string", "example": "Amsterdam" }, "country": { "type": "string", "description": "A country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.", "example": "NL" } } }, "registrationNumber": { "type": "string", "description": "The registration number of the organization at their local chamber of commerce.", "example": "12345678" }, "vatNumber": { "type": [ "string", "null" ], "description": "The VAT number of the organization, if based in the European Union or in The United Kingdom. VAT numbers are verified against the international registry *VIES*.\n\nThe field is not present for merchants residing in other countries.", "example": "NL123456789B01" }, "vatRegulation": { "type": [ "string", "null" ], "description": "Mollie applies Dutch VAT for merchants based in The Netherlands, British VAT for merchants based in The United Kingdom, and shifted VAT for merchants in the European Union.\n\nThe field is not present for merchants residing in other countries.\n\nPossible values: `dutch` `british` `shifted`", "example": "dutch" }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "properties": { "self": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "dashboard": { "description": "Direct link to the organization's Mollie dashboard.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } }, "onboarding": { "type": "object", "required": [ "resource", "name", "signedUpAt", "status", "canReceivePayments", "canReceiveSettlements", "_links" ], "properties": { "resource": { "type": "string", "description": "Indicates the response contains an onboarding status object. Will always contain the string `onboarding` for this resource type.", "readOnly": true, "default": "onboarding" }, "name": { "type": "string", "description": "The name of the organization.", "example": "My webshop", "readOnly": true }, "status": { "allOf": [ { "type": "string", "description": "The current status of the organization's onboarding process.\n\nPossible values: `needs-data` `in-review` `completed`", "x-enumDescriptions": { "needs-data": "The merchant needs to provide additional information", "in-review": "The merchant provided all information, awaiting review from Mollie", "completed": "The onboarding is completed" }, "example": "completed" } ], "readOnly": true }, "canReceivePayments": { "type": "boolean", "description": "Whether the organization can receive payments.", "example": true, "readOnly": true }, "canReceiveSettlements": { "type": "boolean", "description": "Whether the organization can receive settlements to their external bank account.", "example": true, "readOnly": true }, "signedUpAt": { "type": "string", "description": "The sign up date time of the organization in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.", "example": "2023-01-15T13:45:30+00:00", "readOnly": true }, "_links": { "type": "object", "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.", "properties": { "self": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "dashboard": { "description": "Direct link to the onboarding process in the Mollie dashboard. The merchant can be redirected to this page to complete their onboarding.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "organization": { "description": "The API resource URL of the organization.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } }, "readOnly": true } } }, "capabilities": { "type": "object", "required": [ "resource", "name", "status", "statusReason", "requirements" ], "properties": { "resource": { "type": "string", "description": "Always the word `capability` for this resource type.", "example": "capability" }, "name": { "type": "string", "description": "A unique name for this capability like `payments` / `settlements`.", "example": "payments" }, "status": { "type": "string", "enum": [ "unrequested", "enabled", "disabled", "pending" ], "example": "pending" }, "statusReason": { "type": [ "string", "null" ], "enum": [ "requirement-past-due", "onboarding-information-needed" ], "example": "requirement-past-due" }, "requirements": { "type": "array", "items": { "type": "object", "required": [ "id", "dueDate", "status", "_links" ], "properties": { "id": { "type": "string", "description": "The name of this requirement, referring to the task to be fulfilled by the organization to enable or re-enable the capability. The name is unique among other requirements of the same capability. Requirements related to the onboarding process start with 'onboarding-', while requirements related to information requests start with 'information-request-'.", "example": "information-request-aml-charities-and-donations" }, "status": { "type": "string", "description": "The status of the requirement depends on its due date. If no due date is given, the status will be `requested`.\n\nPossible values: `currently-due` `past-due` `requested`", "example": "past-due" }, "dueDate": { "type": [ "string", "null" ], "description": "Due date until the requirement must be fulfilled, if any. The date is shown in ISO-8601 format.", "example": "2024-01-01T12:00:00+00:00" }, "_links": { "type": "object", "required": [], "properties": { "dashboard": { "description": "If known, a deep link to the Mollie dashboard of the client, where the requirement can be fulfilled. For example, where necessary documents are to be uploaded.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } } } } } } } } } } } } ] } } } }, "_links": { "type": "object", "description": "Links to help navigate through the lists of items. Every URL object will contain an `href` and a `type` field.", "required": [ "self", "previous", "next", "documentation" ], "properties": { "self": { "description": "The URL to the current set of items.", "type": "object", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "previous": { "description": "The previous set of items, if available.", "type": [ "object", "null" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "next": { "description": "The next set of items, if available.", "type": [ "object", "null" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } }, "documentation": { "type": "object", "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "description": "The actual URL string.", "example": "https://..." }, "type": { "type": "string", "description": "The content type of the page or endpoint the URL points to.", "example": "application/hal+json" } } } } } } }, "examples": { "list-clients-200-1": { "summary": "A list of client objects", "value": { "count": 1, "_embedded": { "clients": [ { "resource": "client", "id": "org_12345678", "commission": { "count": 0 }, "organizationCreatedAt": "2023-04-06 13:10:19+00:00", "_links": { "self": { "href": "...", "type": "application/hal+json" } } } ] }, "_links": { "self": { "href": "...", "type": "application/hal+json" }, "previous": null, "next": { "href": "https://api.mollie.com/v2/clients?from=org_63916732&limit=5", "type": "application/hal+json" }, "documentation": { "href": "...", "type": "text/html" } } } } } } } }, "400": { "description": "The request contains issues. For example, if the specified `from` value is not a valid ID.", "content": { "application/hal+json": { "schema": { "type": "object", "description": "An error response object.", "required": [ "status", "title", "detail", "_links" ], "properties": { "status": { "type": "integer", "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.", "minimum": 400, "maximum": 599, "example": 404 }, "title": { "type": "string", "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.", "example": "Not Found" }, "detail": { "type": "string", "description": "A detailed human-readable description of the error that occurred.", "example": "The resource does not exist" }, "field": { "type": "string", "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.", "example": "description" }, "_links": { "type": "object", "required": [ "documentation" ], "properties": { "documentation": { "type": "object", "description": "The URL to the generic Mollie API error handling guide.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "example": "https://docs.mollie.com/errors" }, "type": { "type": "string", "example": "text/html" } } } } } } }, "example": { "status": 400, "title": "Bad Request", "detail": "Invalid cursor value", "field": "from", "_links": { "documentation": { "href": "...", "type": "text/html" } } } } } }, "404": { "description": "No entity with this ID exists.", "content": { "application/hal+json": { "schema": { "type": "object", "description": "An error response object.", "required": [ "status", "title", "detail", "_links" ], "properties": { "status": { "type": "integer", "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.", "minimum": 400, "maximum": 599, "example": 404 }, "title": { "type": "string", "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.", "example": "Not Found" }, "detail": { "type": "string", "description": "A detailed human-readable description of the error that occurred.", "example": "The resource does not exist" }, "field": { "type": "string", "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.", "example": "description" }, "_links": { "type": "object", "required": [ "documentation" ], "properties": { "documentation": { "type": "object", "description": "The URL to the generic Mollie API error handling guide.", "required": [ "href", "type" ], "properties": { "href": { "type": "string", "example": "https://docs.mollie.com/errors" }, "type": { "type": "string", "example": "text/html" } } } } } } }, "example": { "status": 404, "title": "Not Found", "detail": "No entity exists with token 'uct_abcDEFghij123456789'", "_links": { "documentation": { "href": "...", "type": "text/html" } } } } } } }, "x-speakeasy-pagination": { "type": "url", "outputs": { "nextUrl": "$._links.next.href" } }, "x-readme": { "code-samples": [ { "language": "shell", "code": "curl -X GET https://api.mollie.com/v2/clients \\\n -H \"Authorization: Bearer access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\"" }, { "language": "php", "code": "setAccessToken(\"access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\");\n\n$clients = $mollie->send(new GetPaginatedClientRequest());", "install": "composer require mollie/mollie-api-php" }, { "language": "node", "code": "/*\nWe don't have a Node.js code example for this\nAPI call yet.\n\nIf you have some time to spare, feel free to\nshare suggestions on our Discord:\nhttps://discord.gg/VaTVkXB4aQ\n*/", "install": "npm install @mollie/api-client" }, { "language": "python", "code": "from mollie.api.client import Client\n\nmollie_client = Client()\nmollie_client.set_access_token(\"access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ\")\n\nclients = mollie_client.clients.list()", "install": "pip install mollie-api-python" }, { "language": "ruby", "code": "require 'mollie-api-ruby'\n\nMollie::Client.configure do |config|\n config.api_key = 'access_Wwvu7egPcJLLJ9Kb7J632x8wJ2zMeJ'\nend\n\nclients = Mollie::Client.all", "install": "gem install mollie-api-ruby" } ] } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "x-default": "live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "organizationAccessToken": { "type": "http", "scheme": "bearer", "x-default": "access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM" }, "oAuth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://my.mollie.com/oauth2/authorize", "tokenUrl": "https://api.mollie.com/oauth2/tokens", "scopes": {} } } } } }, "x-readme": { "explorer-enabled": false, "samples-languages": [ "shell", "php", "node", "python", "ruby" ] } } ```