DOCS

New!

/

5 minute read

August 1, 2019

Object Expansion

The Core API provides object expansion as a way to optimize the number of API calls and the size of the responses.

Some objects contain tokens of related objects in their response representations. For example, a card may have an associated user token. By default, a GET request returns an object representation that includes only tokens of associated objects, thus minimizing the response size.

Alternatively, you can use the expand query parameter to include the associated objects in the response, thus decreasing the number of required subsequent API calls. Objects that can be expanded are described in this page.

Query parameter details

Name Type Required Description Allowable Values

expand

string

No

Embeds the associated object of the specified type into the response, for all GET /cards endpoints.

user, cardproduct

Sample requests and responses

To retrieve a card object that includes only the token of the associated user, use the GET request without the expand query parameter:

GET /cards/{card_token}

This request returns a card object that contains the user_token field:

{
  "created_time": "2016-12-28T18:31:23Z",
  "last_modified_time": "2017-02-14T19:32:38Z",
  "token": "my_user_01_card_02",
  "user_token": "my_user_01",
  "card_product_token": "red_cardproduct",
  "last_four": "0865",
  "pan": "1111111824980865",
  "expiration": "1220",
  "expiration_time": "2020-12-31T23:59:59Z",
  "cvv_number": "137",
  "barcode": "25815105237561780909",
  "pin_is_set": false,
  "state": "UNACTIVATED",
  "state_reason": "New card",
  "fulfillment_status": "DIGITALLY_PRESENTED",
  "fulfillment": {
    "shipping": {
      "method": "FEDEX_REGULAR",
      "care_of_line": "my_care_of_value"
    }
  }
}

Is this helpful?

To embed the expanded user object in the response, use the GET request with the expand query parameter:

GET /cards/{card_token}?expand=user

This request returns a card object with the complete user object embedded within it:

{
  "created_time": "2016-12-28T18:31:23Z",
  "last_modified_time": "2017-02-14T19:32:38Z",
  "token": "my_user_01_card_02",
  "user_token": "my_user_01",
  "card_product_token": "red_cardproduct",
  "last_four": "0865",
  "pan": "1111111824980865",
  "expiration": "1220",
  "expiration_time": "2020-12-31T23:59:59Z",
  "cvv_number": "137",
  "barcode": "25815105237561780909",
  "pin_is_set": false,
  "state": "UNACTIVATED",
  "state_reason": "New card",
  "fulfillment_status": "DIGITALLY_PRESENTED",
  "fulfillment": {
    "shipping": {
      "method": "FEDEX_REGULAR",
      "care_of_line": "my_care_of_value"
    }
  },
  "user": {
    "token": "my_user_01",
    "active": true,
    "metadata": {},
    "corporate_card_holder": false,
    "uses_parent_account": false,
    "created_time": "2017-04-07T19:01:08Z",
    "last_modified_time": "2017-04-07T19:01:08Z"
  }
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.