> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Associate with Customer

> Associate a token with another PCI Booking customer, allowing them to perform actions on this token.

> [card] [Third-Party Permissions Guide](https://developers.pcibooking.net/manage-tokens/third-party-permissions.md)
>
> Learn how to share tokens with other PCI Booking customers

Associates a token with another PCI Booking customer (sub-account), granting them permission to use the token in their own API calls. This is useful in marketplace or platform scenarios where multiple parties need access to the same stored card.

## Error Responses

| Code | HTTP Status | Condition |
| - | - | - |
| -1003 | 401 | The token does not exist, was deleted, or you are neither its owner nor a customer the token has been shared with. See [Token Not Found or Not Accessible](https://developers.pcibooking.net/reference/error-handling.md#token-not-found-or-not-accessible). |
| -179 | 400 | userId is empty |

### Error detail

Each condition below gives the exact `moreInfo` text, why it happens and how to resolve it. The full set is on the [Error Handling](https://developers.pcibooking.net/reference/error-handling.md) page.

> [accordion] -125 Bad input data - merchant not found for this account
>
> **HTTP status:** `400`
>
> **`message`:** `Bad input data`
>
> **`moreInfo`:**
>
> ```text theme={null}
> Could not find a valid merchant <merchantId> for <userId>
> ```
>
> **Reason.** The `merchantId` you passed is not a merchant that your account can associate a token with. Either the ID does not exist, or it belongs to an account unrelated to yours.
>
> **How to resolve.**
>
> 1. Check the `merchantId` value. For a property it is the external user ID, not the internal one.
> 2. Confirm the merchant sits under the same parent account as the credential making the call.

> [accordion] -113 This operation is not allowed for the given entity - association must target the primary account
>
> **HTTP status:** `403`
>
> **`message`:** `This operation is not allowed for the given entity`
>
> **`moreInfo`:**
>
> ```text theme={null}
> Please associate the card to the primary property
> Please associate the card to the primary booker - <accountId>
> ```
>
> **Reason.** A token can only be associated with a **primary** account. You passed the ID of a sub-user or a secondary property, which cannot own an association.
>
> **How to resolve.**
>
> 1. Use the primary account's ID instead. When the message names an account ID, that is the one to use.
> 2. Sub-users of the primary account can then use the token without needing their own association.

## Parameters

### Authentication

**API key only.** This endpoint does not accept access tokens or session tokens.

**Authorization** `string` *required*

Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. The `x-pcibooking-api-key` header is also accepted. See the [Authentication guide](https://developers.pcibooking.net/getting-started/authentication.md).

### Path Parameters

**cardToken** `string` *required*

The token ID as returned by one of the tokenization methods.

**userID** `string` *required*

The user ID of a PCI Booking customer ("Booker") that the token should be associated with. You will need to collect this userID from the booker you wish to associate the card with.

```javascript Node.js theme={null}
const response = await fetch(
  'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/user/booker-user-123',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'APIKEY your-api-key'
    }
  }
);

console.log(response.status);
```

```python Python theme={null}
import requests

response = requests.put(
    'https://service.pcibooking.net/api/payments/paycard/2821a46d80e14d1b96a7f18f1b81926d/user/booker-user-123',
    headers={'Authorization': 'APIKEY your-api-key'}
)

print(response.status_code)
```

## Response

**200** - Association created. Empty response body.

```text 200 theme={null}
Empty response body. Association created successfully.
```

```json 400 theme={null}
{
    "code": -125,
    "message": "Bad input data",
    "moreInfo": "Could not find a valid user",
    "errorList": null
}
```

```text 401 theme={null}
Empty response body.
Authentication failed: the API key, session token or access token is missing or was not accepted.
See "Authentication and Permission Failures" on the Error Handling page.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.