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

# Tokenize from sFTP

> Download a file from an sFTP server through PCI Booking. Card data is extracted, tokenized, and the sanitized file content is returned.

<Card title="File Transfer Tokenization Guide" icon="book" href="/capture-cards/file-transfer-tokenization">
  Tokenize card data from SFTP file transfers
</Card>

Also available over FTPS:

```
GET https://service.pcibooking.net/api/ftps/{serverAddress}/{folderPath}/{fileName}
```

PCI Booking connects to the sFTP server, downloads the file, tokenizes any card data found in it (based on the specified filter), and returns the sanitized file content with the following custom headers:

| Header                               | Description                                                                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `X-pciBooking-cardUri`               | Semicolon-separated list of token URIs for each card tokenized.                                                     |
| `X-pciBooking-Tokenization-Errors`   | Errors encountered during tokenization (e.g. invalid card number, missing fields). Present only if errors occurred. |
| `X-pciBooking-Tokenization-Warnings` | Warnings encountered during tokenization (e.g. expired card accepted). Present only if warnings occurred.           |

<Note>
  If the path ends with `/`, PCI Booking returns a directory listing instead of downloading a file.
</Note>

## Error Responses

| Code    | HTTP Status | Condition                                                              |
| ------- | ----------- | ---------------------------------------------------------------------- |
| `-1003` | `401`       | Authorization token is missing or invalid.                             |
| `-125`  | `400`       | Invalid host format (e.g. multiple colons in the server address).      |
| `-125`  | `400`       | Invalid or missing Basic Auth credentials in the Authorization header. |
| `-125`  | `400`       | The requested filter name is not recognized.                           |
| `-1003` | `401`       | SFTP/FTPS login failed (invalid server credentials).                   |
| `-160`  | `404`       | File download or directory listing failed on the remote server.        |

## Parameter Constraints

* **serverAddress**: Format is `hostname` or `hostname:port`. Only one colon is allowed. Default port is 22.
* **filter**: Must be one of: `GBT`, `SIMPLECSV`, `SIMPLEJSON`, `AIR`, `IUR`, `TADC`, `CSV`. Case-insensitive.
* **Authorization header**: Must contain valid Basic Auth credentials (`username:password`) for the SFTP/FTPS server.

## Parameters

### Authentication

<Warning>
  This is a browser-facing endpoint. Use one of the authentication methods below instead of the API key shown above.
</Warning>

<ParamField query="accessToken" type="string">
  Recommended. A long-lived token for browser-side calls. [How to generate](/getting-started/authentication#access-token).
</ParamField>

<ParamField query="sessionToken" type="string">
  Alternative. Valid for 5 minutes. [How to generate](/api-reference/general/start-temporary-session).
</ParamField>

If both are provided, the session token takes precedence.

### Path Parameters

<ParamField path="serverAddress" type="string" required>
  The sFTP server address. This can be an IP address or domain name. If required, add the port number with a colon. For example: `fsgatewaytest.aexp.com:22` or `10.200.1.10`.
</ParamField>

<ParamField path="folderPath" type="string" required>
  The folder path where the file should be downloaded from. This can be an individual folder or a full path.
</ParamField>

<ParamField path="fileName" type="string" required>
  The file name to download, including extension. For example: `PCIBTST.xml`.
</ParamField>

### Query String

<ParamField query="filter" type="string" required>
  The file format filter that tells PCI Booking how to parse the file content and locate card data.
</ParamField>

<ParamField query="timeout" type="string">
  The number of seconds PCI Booking should wait for the sFTP server to respond.
</ParamField>

<ParamField query="ref" type="string">
  A reference value which can be used to query for this card token.
</ParamField>

<ParamField query="merchantId" type="string">
  The user ID of the property to associate the token with. Found under "Property settings" in the user's site.
</ParamField>

<ParamField query="eliminateCardDuplication" type="boolean" default="false">
  Controls whether PCI Booking checks if the card already exists as a token in your account.

  * **`true`**: PCI Booking looks up the card in your stored tokens. If a match is found, the existing token URI is returned instead of creating a new one.
  * **`false`** (default): A new token is always created, even if the same card was previously stored.
</ParamField>

### Headers

<ParamField header="Content-Encoding" type="string">
  PCI Booking supports request compression in `gzip` and `deflate` formats. Set this header as needed. Omit if no compression is required.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const serverAddress = 'sftp.thirdparty.com:22';
  const folderPath = 'reports/daily';
  const fileName = 'reservations.xml';

  const params = new URLSearchParams({
    filter: 'GBT',
    ref: 'import-2024-01',
    timeout: '30'
  });

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

  const tokenUri = response.headers.get('X-pciBooking-cardUri');
  console.log('Token URI:', tokenUri);

  const data = await response.text();
  console.log('Sanitized file content:', data);
  ```

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

  server_address = 'sftp.thirdparty.com:22'
  folder_path = 'reports/daily'
  file_name = 'reservations.xml'

  response = requests.get(
      f'https://service.pcibooking.net/api/sftp/{server_address}/{folder_path}/{file_name}',
      params={
          'filter': 'GBT',
          'ref': 'import-2024-01',
          'timeout': '30'
      },
      headers={
          'Authorization': 'APIKEY your-api-key'
      }
  )

  token_uri = response.headers.get('X-pciBooking-cardUri')
  print('Token URI:', token_uri)
  print('Sanitized file content:', response.text)
  ```
</RequestExample>

## Response

**200** - The file content with card details masked. Token URIs are returned in the `X-pciBooking-cardUri` header.

<Info>
  Remember to set the [CVV Retention Policy](/capture-cards/cvv-retention-policy) on the token.
</Info>

<ResponseExample>
  ```text 200 theme={null}
  The file content is returned with card details replaced by token placeholders.
  The X-pciBooking-cardUri header contains the token URI(s).
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```

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