---
title: "Create client link"
method: POST
path: "/v2/client-links"
tags: ["Client Links API"]
---

# Create client link

`POST /v2/client-links`

## Request

- Base URL: `https://api.mollie.com`
- URL: `https://api.mollie.com/v2/client-links`
- Auth: HTTP bearer

Link a new or existing organization to your OAuth application, in effect creating a new client. The response contains a `clientLink` where you should redirect your customer to.

## Redirecting the Customer

The `clientLink` URL behaves similarly to a standard OAuth authorization URL. Therefore, after receiving the `clientLink` URL in the API response, you need to **append the following query parameters** *before* redirecting the customer:

* `client_id` _string (required)_

  The client ID you received when you registered your OAuth app. The ID starts with `app_`. For example: `app_abc123qwerty`.

* `state` _string (required)_

  A random string **generated by your app** to prevent CSRF attacks. This will be reflected in the `state` query parameter when the user returns to the `redirect_uri` after authorizing your app.

* `scope` _string (required)_

  A space-separated list of permissions ('scopes') your app requires. See the [permissions list](https://docs.mollie.com/docs/permissions) for more information about the available scopes.

  We recommend at least : `onboarding.read onboarding.write`

* `approval_prompt` _string_

  Can be set to `force` to force showing the consent screen to the merchant, *even when it is not necessary*. If you force an approval prompt and the user creates a new authorization, previously active authorizations will be revoked.

  Possible values: `auto` `force` (default: `auto`)

### Example of a Complete Redirect URL

After adding the above url parameter your URL will look something like this and you can redirect your client to this page:

``` https://my.mollie.com/dashboard/client-link/{id}?client_id={your_client_id}&state={unique_state}&scope=onboarding.read%20onboarding.write ```

## Error Handling

Error handling is also dealt with similar to the [Authorize](https://docs.mollie.com/reference/authorize) endpoint: the customer is redirected back to your app's redirect URL with the `error` and `error_description` parameters added to the URL.

> 🚧
>
> A client link must be used within 30 days of creation. After that period, it will expire and you will need to create a new client link.

> 🔑 Access with
>
> [Advanced access token with **clients.write**](/reference/authentication)

## Request body

- object
  - `resource` string: Indicates the response contains a client link object. Will always contain the string `client-link` for this endpoint.
  - `id` string: The identifier uniquely referring to this client link. Example: `cl_vZCnNQsV2UtfXxYifWKWH`.
  - `owner` object, required: Personal data of your customer.
    - `email` string, required: The email address of your customer. If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    - `givenName` string, required: The given name (first name) of your customer.
    - `familyName` string, required: The family name (surname) of your customer.
    - `locale` string, nullable: Preset the language to be used for the login screen, if applicable. For the consent screen, the preferred language of the logged in merchant will be used and this parameter is ignored. When this parameter is omitted, the browser language will be used instead. Possible values: `ca_ES` `cs_CZ` `da_DK` `de_AT` `de_CH` `de_DE` `de_LU` `el_GR` `en_BE` `en_GB` `en_NL` `en_US` `es_ES` `fi_FI` `fr_BE` `fr_FR` `fr_LU` `hu_HU` `is_IS` `it_IT` `lt_LT` `lv_LV` `nb_NO` `nl_BE` `nl_NL` `pl_PL` `pt_PT` `sk_SK` `sl_SI` `sv_SE` `tr_TR`
  - `name` string, required: Name of the organization.
  - `address` object, required: Address of the organization.
    - `streetAndNumber` string, nullable: The street name and house number of the organization.
    - `postalCode` string, nullable: The postal code of the organization. Required if a street address is provided and if the country has a postal code system.
    - `city` string, nullable: The city of the organization. Required if a street address is provided.
    - `country` string, required: The country of the address in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
  - `registrationNumber` string, nullable: The registration number of the organization at their local chamber of commerce.
  - `vatNumber` string, nullable: The VAT number of the organization, if based in the European Union. VAT numbers are verified against the international registry *VIES*.
  - `legalEntity` string: The legal entity type of the organization, based on its country of origin. Please refer to the [legal entity list](common-data-types#legal-entity) for all possible options.
  - `registrationOffice` string: The registration office that the organization was registered at. Please refer to the [registration office list](common-data-types#registration-office) for all possible options.
  - `incorporationDate` string, nullable: The incorporation date of the organization (format `YYYY-MM-DD`)
  - `_links` object: An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.
    - `self` object: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.
    - `clientLink` object: The link you can send your customer to, where they can either log in and link their account, or sign up and proceed with onboarding.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.
    - `documentation` object: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.

## Response `201`

The newly created client link object.

- object
  - `resource` string, required: Indicates the response contains a client link object. Will always contain the string `client-link` for this endpoint.
  - `id` string, required: The identifier uniquely referring to this client link. Example: `cl_vZCnNQsV2UtfXxYifWKWH`.
  - `owner` object: Personal data of your customer.
    - `email` string, required: The email address of your customer. If the domain contains non-ASCII characters, encode it as Punycode per [RFC 3492](https://www.rfc-editor.org/rfc/rfc3492).
    - `givenName` string, required: The given name (first name) of your customer.
    - `familyName` string, required: The family name (surname) of your customer.
    - `locale` string, nullable: Preset the language to be used for the login screen, if applicable. For the consent screen, the preferred language of the logged in merchant will be used and this parameter is ignored. When this parameter is omitted, the browser language will be used instead. Possible values: `ca_ES` `cs_CZ` `da_DK` `de_AT` `de_CH` `de_DE` `de_LU` `el_GR` `en_BE` `en_GB` `en_NL` `en_US` `es_ES` `fi_FI` `fr_BE` `fr_FR` `fr_LU` `hu_HU` `is_IS` `it_IT` `lt_LT` `lv_LV` `nb_NO` `nl_BE` `nl_NL` `pl_PL` `pt_PT` `sk_SK` `sl_SI` `sv_SE` `tr_TR`
  - `name` string: Name of the organization.
  - `address` object: Address of the organization.
    - `streetAndNumber` string, nullable: The street name and house number of the organization.
    - `postalCode` string, nullable: The postal code of the organization. Required if a street address is provided and if the country has a postal code system.
    - `city` string, nullable: The city of the organization. Required if a street address is provided.
    - `country` string, required: The country of the address in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
  - `registrationNumber` string, nullable: The registration number of the organization at their local chamber of commerce.
  - `vatNumber` string, nullable: The VAT number of the organization, if based in the European Union. VAT numbers are verified against the international registry *VIES*.
  - `legalEntity` string: The legal entity type of the organization, based on its country of origin. Please refer to the [legal entity list](common-data-types#legal-entity) for all possible options.
  - `registrationOffice` string: The registration office that the organization was registered at. Please refer to the [registration office list](common-data-types#registration-office) for all possible options.
  - `incorporationDate` string, nullable: The incorporation date of the organization (format `YYYY-MM-DD`)
  - `_links` object, required: An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.
    - `self` object: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.
    - `clientLink` object: The link you can send your customer to, where they can either log in and link their account, or sign up and proceed with onboarding.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.
    - `documentation` object: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.

## Other responses

- `404`: No entity with this ID exists.
- `422`: The request contains issues. For example, if the `owner` field is missing.
- `429`: Rate Limit has been reached.

---

[API](https://skmtc.dev/mollie/apis/mollie-connect.md) - [All operations](https://skmtc.dev/mollie/apis/mollie-connect/llms.txt) - [OpenAPI document](https://skmtc.dev/mollie/apis/mollie-connect/revisions/65271e79a786?raw)