> ## 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.

# Query Tokens

> Search for tokens by creator reference. Returns metadata for up to 100 matching tokens, with pagination support.

<Card title="Query & Retrieve Guide" icon="book" href="/manage-tokens/query-retrieve">
  Search for tokens and retrieve their metadata
</Card>

Use this endpoint to search for stored card tokens by the reference value you assigned during tokenization. It returns metadata (card type, last digits, expiration, associations) for up to 100 matching tokens per request, with pagination support for larger result sets.

## Parameter Constraints

| Parameter | Type    | Required | Constraints                                                |
| --------- | ------- | -------- | ---------------------------------------------------------- |
| to        | integer | No       | Maximum number of results to return. Defaults to `100`     |
| from      | integer | No       | Pagination offset (chronological counter). Defaults to `0` |
| ref       | string  | No       | Filter by creator reference value (exact match)            |
| property  | string  | No       | Filter by associated property ID                           |

<Note>This endpoint is rate limited. Standard authentication errors apply (code -1003, HTTP 401).</Note>

## Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Query String

<ParamField query="ref" type="string" required>
  The reference value provided during tokenization to locate this token. Exact match only.
</ParamField>

<ParamField query="from" type="integer" default="0">
  Chronological counter of tokens from which to start retrieving.
</ParamField>

<ParamField query="to" type="integer" default="100">
  The number of tokens to return in the response.
</ParamField>

<ParamField query="property" type="string">
  The property ID of the hotel the tokens were associated with. You would have used [this method](/api-reference/manage-tokens/associate-with-customer) to set up the association first.
</ParamField>

## Request Example

Query all tokens created with the reference `booking-12345`, returning the first 10 results:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -G "https://service.pcibooking.net/api/payments/paycard/meta" \
      -H "Authorization: APIKEY your-api-key" \
      --data-urlencode "ref=booking-12345" \
      --data-urlencode "from=0" \
      --data-urlencode "to=10"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      ref: "booking-12345",
      from: "0",
      to: "10"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard/meta?${params}`,
      {
        headers: {
          "Authorization": "APIKEY your-api-key"
        }
      }
    );

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        "https://service.pcibooking.net/api/payments/paycard/meta",
        headers={"Authorization": "APIKEY your-api-key"},
        params={
            "ref": "booking-12345",
            "from": 0,
            "to": 10
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

To filter by property, add the `property` parameter:

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -G "https://service.pcibooking.net/api/payments/paycard/meta" \
      -H "Authorization: APIKEY your-api-key" \
      --data-urlencode "ref=booking-12345" \
      --data-urlencode "property=hotel-sunrise"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const params = new URLSearchParams({
      ref: "booking-12345",
      property: "hotel-sunrise"
    });

    const response = await fetch(
      `https://service.pcibooking.net/api/payments/paycard/meta?${params}`,
      {
        headers: {
          "Authorization": "APIKEY your-api-key"
        }
      }
    );

    const data = await response.json();
    console.log(data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.get(
        "https://service.pcibooking.net/api/payments/paycard/meta",
        headers={"Authorization": "APIKEY your-api-key"},
        params={
            "ref": "booking-12345",
            "property": "hotel-sunrise"
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    ref: 'booking-12345',
    from: '0',
    to: '10'
  });

  const response = await fetch(
    `https://service.pcibooking.net/api/payments/paycard/meta?${params}`,
    {
      headers: {
        'Authorization': 'APIKEY your-api-key'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.get(
      'https://service.pcibooking.net/api/payments/paycard/meta',
      headers={'Authorization': 'APIKEY your-api-key'},
      params={
          'ref': 'booking-12345',
          'from': 0,
          'to': 10
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

**200** - An array of token metadata objects. Each item contains the fields below. For the single-token equivalent (which also returns `CreatorReference` and `VirtualInfo`), see [Retrieve Token Metadata](/api-reference/manage-tokens/retrieve-token-metadata).

<ParamField body="CreateDate" type="string">
  The date and time the token was created (ISO 8601).
</ParamField>

<ParamField body="CardType" type="string">
  The card brand (e.g. `Visa`, `Mastercard`, `Amex`). See [supported card types](/reference/card-types).
</ParamField>

<ParamField body="LeadingDigits" type="string">
  The first 6 digits (BIN) of the card number.
</ParamField>

<ParamField body="LastDigits" type="string">
  The last 4 digits of the card number.
</ParamField>

<ParamField body="ExpirationYear" type="integer">
  The card expiration year.
</ParamField>

<ParamField body="ExpirationMonth" type="integer">
  The card expiration month.
</ParamField>

<ParamField body="OwnerID" type="string">
  The cardholder ID, if provided at tokenization time.
</ParamField>

<ParamField body="OwnerName" type="string">
  The name on the card, if provided at tokenization time.
</ParamField>

<ParamField body="UserID" type="string">
  The PCI Booking user ID that owns this token.
</ParamField>

<ParamField body="IssueNumber" type="string">
  The card issue number (used by some card schemes).
</ParamField>

<ParamField body="URI" type="string">
  The full token URI for use in API calls.
</ParamField>

<ParamField body="CvvExists" type="boolean">
  Whether CVV data is currently stored on this token.
</ParamField>

<ParamField body="EndRetentionDate" type="string">
  The date after which the CVV will be automatically deleted (ISO 8601). Reflects the [CVV retention policy](/capture-cards/cvv-retention-policy).
</ParamField>

<ParamField body="AssociatedMerchants" type="string[]">
  List of PCI Booking customer (booker) user IDs associated with this token.
</ParamField>

<ParamField body="AssociatedProperties" type="string[]">
  List of property user IDs associated with this token.
</ParamField>

<ParamField body="ThreeDSecureInfo" type="object">
  3D Secure authentication data, if stored on this token. See [3D Secure Authentication](/manage-tokens/3ds-auth-management) for field details.
</ParamField>

<ParamField body="NetworkTokenScheme" type="string">
  The card network scheme if this is a network token (e.g. `Visa`, `Mastercard`). `null` for regular cards.
</ParamField>

<ParamField body="NetworkTokenId" type="string">
  The network token identifier assigned by the card scheme. `null` for regular cards.
</ParamField>

<ParamField body="TokenLocation" type="string">
  The geographic storage location of the token data. `null` for default (in-table) storage.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  [
      {
          "CreateDate": "2020-05-19T16:51:00",
          "CardType": "Visa",
          "LastDigits": "5005",
          "LeadingDigits": "491891",
          "ExpirationYear": 2020,
          "ExpirationMonth": 7,
          "OwnerID": "",
          "OwnerName": "Juan Dela Cruz",
          "UserID": "myUser",
          "IssueNumber": "2",
          "URI": "https://service.pcibooking.net/api/payments/paycard/eb454e0462d548ddbc6e6c2193b749a9",
          "EndRetentionDate": "2017-07-08T00:00:00",
          "CvvExists": true,
          "AssociatedMerchants": ["userID1", "userID2"],
          "AssociatedProperties": ["hotel1", "hotel2"],
          "ThreeDSecureInfo": {
              "Token": "42c775efa8b04b1d8bf14ef49a9e45e5",
              "ThreeDSSessionID": "uOrDbh0dEimUDmB3Vvn2f5CAM9B1bMQX",
              "Indication": "Authenticated",
              "AuthenticationValue": "AJkBAoEREQAAAAB4hABwcAAAAAA=",
              "Eci": "05",
              "XID": "861433f4-abff-4c40-b2fd-fea208856a33",
              "AcsTransactionId": "e7a46959-9630-413e-ab56-4e399b96244a",
              "Version": "2.1.0",
              "MerchantName": "PCI Booking * Hotelreservation"
          },
          "NetworkTokenScheme": null,
          "NetworkTokenId": null,
          "TokenLocation": null
      }
  ]
  ```

  ```json 401 theme={null}
  {
      "code": -1003,
      "message": "Not authorized to access this resource",
      "moreInfo": "Bad or missing authorization data, expected APIKEY",
      "errorList": null
  }
  ```
</ResponseExample>