Using Postman

This section provides an introduction to using the Thredd REST API collection in Postman.

• Prerequisites
• Install the Thredd Sandbox Postman Collection
• Assign your Client Credentials
• Use the Postman Collection

Prerequisites

• Download and install the Postman app. See Download Postman.
• Download the latest Thredd REST API Collection (available on the API Explorer page).

Install the Thredd Sandbox Postman Collection

1. Open Postman.
2. Click the Import button. A window will open.
3. Navigate to the directory where the collection is saved and select the Thredd REST API file Thredd_Sandbox_REST_API_External_Postman_Collection.postman_collection.

Assign your Client Credentials

When you sign up to the Thredd Sandbox environment you will be provided with your own client id and client secret. These will need to be entered into the Variables section of the Postman Collection before you can start using the endpoints.

To assign your client credentials:

1. Click on the Thredd Sandbox REST API External Postman Collection in Postman.

2. Open the Variables tab.

3. Enter your client id in the Initial Value and Current Value fields.

4. Enter your client secret in the Initial Value and Current Value fields.

5. Click the Save button.

The details will be saved and you can now start using the Thredd Sandbox Postman Collection.

Use the Postman Collection

The Thredd REST API collection appears in the left-hand column of your Postman workspace.

Generate the OAuth Token

Generation of the OAuth token is done at the top level of the collection so you only need to authorise a token once. The URL used to retrieve a token is in place so you don't need to enter any details to retrieve an auth token.

1. Select the ThreddSandbox REST API Postman Collection collection.

2. Click Get New Access Token button in the Authorization tab.

3. Click Proceed, then click Use Token.

The token will be applied to every endpoint in the collection.

Get your Product ID

You will need a customer specific Product ID before you can create a card. You can retrieve a product ID by running the Get Product API endpoint.

1. Select the Get Product API endpoint.
2. Click Send.

Thredd returns a 200 Ok response, containing the productID field, as shown in the example below.

[
    {
        "productID": 1234,
        "productName": "Sandbox Product",
        "accountCode": "01",
        "schemeName": "Sandbox Scheme",
        "currencyCode": "GBP"
    }
]

Create a Card

1. Select the Create a Card API endpoint.
2. Select the Body tab and enter the details of the card, replacing the example values with your required details. This includes the customer-specific ProductID from the Get Product endpoint, which should be entered into the CardProduct field.

3. Click Send.

Thredd returns a 200 Ok response, containing the Thredd public token, as shown in the example below.

{
  "publicToken": "986916553",
  "customerReference": "",
  "embossName": "Mr Jane Doe",
  "maskedPan": "999999******1160",
  "startDate": "2022-09-05",
  "expiryDate": "2023-09-05"
}

The public token provides a unique identifier for your card. You can use this public token in all subsequent requests related to the card.

Apply publicToken as a Variable

Almost all endpoints are set up to use the publicToken set in the Variables tab of the collection. To set the publicToken variable:

1. Select the Variables tab in the Thredd Sandbox REST API Postman Collection.

2. Enter the publicToken you want to use in the Initial Value and Current Value columns.

3. Click Save.

The collection is saved. All endpoints will use the variable and run using the set publicToken.

Retrieve the Details of a Card

1. Select the Retrieve a Card API endpoint.
2. If required, generate a new access token.

Thredd returns a 200 Ok response, containing details of the card linked to the Thredd public token, as shown in the example below.

{
     "cardHolder": {
          "title": "Mrs",
          "firstName": "Jane",
          "lastName": "Doe",
          "dateOfBirth": "1963-11-22"
     },
     "address": {
          "addressLine1": "22 Boulder Avenue",
          "postCode": "S25 5HT",
          "country": "GBR"
     },
     "fulfilment": {
          "addressLine1": "22 Boulder Avenue",
          "postCode": "S25 5HT",
          "country": "GBR"
     },
     "manufacturingDetails": {
          "imageDetails": {
               "imageId": "34",
               "logoBackId": "434",
               "logoFrontId": "4343"
          },
          "cardManufacturer": "434",
          "deliveryMethod": "StandardDelivery",
          "carrierType": "3443"
     },
     "cardType": "Physical",
     "cardProduct": 1234,
     "designId": "New Card Brand"
}

Why not try our recipes?

We've created a selection of recipes that will take you through the process of using some of our key endpoints - from creating a card, to performing a contactless transaction on the card. Use the buttons below to learn about each of the endpoints as we step you through the process of performing each transaction.