Card

Cards act as external identifiers that can be linked to customers, and customers can have any number of cards linked to their account.

The card model

The card model contains identifying information about the card.

Properties

Name
id
Type
string
Description
Unique identifier for the currency.
Name
number
Type
string
Description
Varying length alphanumeric external identifier for the card.
Name
pin
Type
string or null
Description
Used as a validation passcode for card activities.
Name
data
Type
object
Description
An arbitrary JSON object containing additional information about the card.
Name
date_created
Type
string
Description
Timestamp of when the card was first created.
Name
date_updated
Type
string
Description
Timestamp of when the card was last updated.
Name
status
Type
string
Description
A string enum for indicating the current status of the card.

GET/cards

Retrieve a list of cards

This endpoint allows you to retrieve a paginated list of cards. By default, this will include the 25 most recent objects, starting with the most recent.

Query parameters

Name
limit
Type
integer
Description
The maximum number of entries to include in the response.

Name
page
Type
integer
Description
An offset to determine which groups of results to return.

Name
query
Type
string
Description
A search string which can be used to filter results by various criteria (see below).

Filter parameters

These attributes can be used to filter the result set returned by the API. They are included as a space-delimited string of key:value pairs.

Name
n
Type
string
Description
Number of the card

Request

GET

/cards

curl -G https://api.spoonity.com/cards \
  -H "Authorization: Bearer {token}"

Response

{
  "items": [
    {
      "id": "card_32f9395aa82770bb",
      "number": "999910888802",
      "pin": "123",
      "data": {
        "image":"https://example.com/i/card_face.jpg",
        "batch":"BT-001"
      },
      "date_created": "2026-02-02T13:48:05.683Z",
      "date_updated": "2026-02-02T13:48:05.683Z",
      "status": "ACTIVE"
    }
  ],
  "next": "https://api.spoonity.com/cards?limit=25&page=2",
  "prev": null
}

GET/cards/:id

Retrieve a particular card

This endpoint allows you to retrieve a specific card by ID.

Path parameters

Name
id
Type
string
Description
The card ID.

Request

GET

/currencies/:id

curl -G https://api.spoonity.com/cards/:id \
-H "Authorization: Bearer {token}"

Response

{
  "id": "card_32f9395aa82770bb",
  "number": "999910888802",
  "pin": "123",
  "data": {
    "image":"https://example.com/i/card_face.jpg",
    "batch":"BT-001"
  },
  "date_created": "2026-02-02T13:48:05.683Z",
  "date_updated": "2026-02-02T13:48:05.683Z",
  "status": "ACTIVE"
}

POST/cards

Create a card

This endpoint allows you to add a new card. A card must include a number.

Required attributes

Name
number
Type
string
Description
The card number.

Optional attributes

Name
pin
Type
string
Description
A short validation passcode for card activities.

Name
data
Type
object
Description
An arbitrary JSON object containing additional information about the card.

Request

POST

/cards

curl -G https://api.spoonity.com/cards \
-H "Authorization: Bearer {token}" \
-d number="999910888802"

Response

{
  "id": "card_32f9395aa82770bb",
  "number": "999910888802",
  "pin": null,
  "data": {},
  "date_created": "2026-02-02T13:48:05.683Z",
  "date_updated": "2026-02-02T13:48:05.683Z",
  "status": "ACTIVE"
}

PUT/cards/:id

Update a card

This endpoint allows you to update a card. A card's data and status can be updated.

Path parameters

Name
id
Type
string
Description
The card ID.

Optional attributes

Name
data
Type
object
Description
An arbitrary JSON object containing additional information about the card.

Name
status
Type
string
Description
A status enum. Cards can exist in either an ACTIVE or ARCHIVED state.

Request

PUT

/cards/:id

curl -G https://api.spoonity.com/cards/:id \
--request PUT \
-H "Authorization: Bearer {token}" \
-d status="INACTIVE"

Response

{
  "id": "card_32f9395aa82770bb",
  "number": "999910888802",
  "pin": "123",
  "data": {
    "image":"https://example.com/i/card_face.jpg",
    "batch":"BT-001"
  },
  "date_created": "2026-02-02T13:48:05.683Z",
  "date_updated": "2026-02-02T13:48:05.683Z",
  "status": "INACTIVE"
}

DELETE/cards/:id

Delete a card

This endpoint allows you to delete a card. Deleted cards will no longer be accessible.

Path parameters

Name
id
Type
string
Description
The card ID.

Request

DELETE

/cards/:id

curl -G https://api.spoonity.com/cards/:id \
--request DELETE \
-H "Authorization: Bearer {token}"

Response

{}

Card

Cards act as external identifiers that can be linked to customers, and customers can have any number of cards linked to their account.

The card model

The card model contains identifying information about the card.

Properties

Name
id
Type
string
Description
Unique identifier for the currency.
Name
number
Type
string
Description
Varying length alphanumeric external identifier for the card.
Name
pin
Type
string or null
Description
Used as a validation passcode for card activities.
Name
data
Type
object
Description
An arbitrary JSON object containing additional information about the card.
Name
date_created
Type
string
Description
Timestamp of when the card was first created.
Name
date_updated
Type
string
Description
Timestamp of when the card was last updated.
Name
status
Type
string
Description
A string enum for indicating the current status of the card.

GET/cards

Retrieve a list of cards

This endpoint allows you to retrieve a paginated list of cards. By default, this will include the 25 most recent objects, starting with the most recent.

Query parameters

Name
limit
Type
integer
Description
The maximum number of entries to include in the response.

Name
page
Type
integer
Description
An offset to determine which groups of results to return.

Name
query
Type
string
Description
A search string which can be used to filter results by various criteria (see below).

Filter parameters

These attributes can be used to filter the result set returned by the API. They are included as a space-delimited string of key:value pairs.

Name
n
Type
string
Description
Number of the card

Request

GET

/cards

curl -G https://api.spoonity.com/cards \
  -H "Authorization: Bearer {token}"

Response

{
  "items": [
    {
      "id": "card_32f9395aa82770bb",
      "number": "999910888802",
      "pin": "123",
      "data": {
        "image":"https://example.com/i/card_face.jpg",
        "batch":"BT-001"
      },
      "date_created": "2026-02-02T13:48:05.683Z",
      "date_updated": "2026-02-02T13:48:05.683Z",
      "status": "ACTIVE"
    }
  ],
  "next": "https://api.spoonity.com/cards?limit=25&page=2",
  "prev": null
}

GET/cards/:id

Retrieve a particular card

This endpoint allows you to retrieve a specific card by ID.

Path parameters

Name
id
Type
string
Description
The card ID.

Request

GET

/currencies/:id

curl -G https://api.spoonity.com/cards/:id \
-H "Authorization: Bearer {token}"

Response

{
  "id": "card_32f9395aa82770bb",
  "number": "999910888802",
  "pin": "123",
  "data": {
    "image":"https://example.com/i/card_face.jpg",
    "batch":"BT-001"
  },
  "date_created": "2026-02-02T13:48:05.683Z",
  "date_updated": "2026-02-02T13:48:05.683Z",
  "status": "ACTIVE"
}

POST/cards

Create a card

This endpoint allows you to add a new card. A card must include a number.

Required attributes

Name
number
Type
string
Description
The card number.

Optional attributes

Name
pin
Type
string
Description
A short validation passcode for card activities.

Name
data
Type
object
Description
An arbitrary JSON object containing additional information about the card.

Request

POST

/cards

curl -G https://api.spoonity.com/cards \
-H "Authorization: Bearer {token}" \
-d number="999910888802"

Response

{
  "id": "card_32f9395aa82770bb",
  "number": "999910888802",
  "pin": null,
  "data": {},
  "date_created": "2026-02-02T13:48:05.683Z",
  "date_updated": "2026-02-02T13:48:05.683Z",
  "status": "ACTIVE"
}

PUT/cards/:id

Update a card

This endpoint allows you to update a card. A card's data and status can be updated.

Path parameters

Name
id
Type
string
Description
The card ID.

Optional attributes

Name
data
Type
object
Description
An arbitrary JSON object containing additional information about the card.

Name
status
Type
string
Description
A status enum. Cards can exist in either an ACTIVE or ARCHIVED state.

Request

PUT

/cards/:id

curl -G https://api.spoonity.com/cards/:id \
--request PUT \
-H "Authorization: Bearer {token}" \
-d status="INACTIVE"

Response

{
  "id": "card_32f9395aa82770bb",
  "number": "999910888802",
  "pin": "123",
  "data": {
    "image":"https://example.com/i/card_face.jpg",
    "batch":"BT-001"
  },
  "date_created": "2026-02-02T13:48:05.683Z",
  "date_updated": "2026-02-02T13:48:05.683Z",
  "status": "INACTIVE"
}

DELETE/cards/:id

Delete a card

This endpoint allows you to delete a card. Deleted cards will no longer be accessible.

Path parameters

Name
id
Type
string
Description
The card ID.

Request

DELETE

/cards/:id

curl -G https://api.spoonity.com/cards/:id \
--request DELETE \
-H "Authorization: Bearer {token}"

Response

{}