Skip to main content

Cards API

The Cards API exposes information about generated card instances, and allows them to be actioned programmatically.

You can interact with the Cards API using Insomnia (follow the Insomnia instructions) or curl.

Detailed specs and examples can be found in the Atomic API spec for the Cards API endpoint.

A credential role of events is required to interact with the Cards API.

This guide lists a few request and response examples using curl. When using curl, you'll need to set up your Authentication first.

Query attributes​

Card instances can be queried and actioned by any combination of the following attributes - all of which are optional:

  • eventName
  • lifecycleId
  • cardTemplateId
  • flowInstanceId
  • flowInvocationId
  • userId
  • status

The eventName attribute is a legacy attribute.

The flowInstanceId is a unique id to identify the instance of an Action Flow.

The flowInvocationId identifies the invocation or API request which triggered the Action Flow instance.

The status of a card refers to one of the possible states it can be in throughout its lifecycle. Read more about this in the Card lifecycle model.

Retrieving cards​

Retrieve cards that match query string:

curl -X GET "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/cards?userId=123&status=active" \
    --header "Authorization: Bearer $TOKEN"

You'll see a response similar to the following:

{
  "data": [
    {
      "eventName": "",
      "eventSource": "live",
      "cardTemplateId": "abc",
      "cardInstanceId": "123",
      "cardTemplateName": "My card",
      "lifecycleId": "def",
      "flowInstanceId": "456",
      "flowInvocationId": "789",
      "definition": {...},
      "payload": {
        "detail": {
          "name": "John Smith"
        },
        "target": {
          "usersById": ["123"]
        },
        "cardOptions": {...},
        "metadata": {...}
      },
      "status": "active",
      "userId": "123",
      "created": "2020-01-14T23:03:04.239Z",
      "updated": "2020-01-14T23:03:04.239Z"
    }
  ]
}

More detailed specs and examples can be found in the Atomic API spec for the Cards API endpoint.

Pagination​

By default, the first 100 cards are returned. To control this, use the limit and offset query parameters, either separately or in combination. For example, to show the second set of 100 cards, pass offset=100. To show 1000 cards, pass limit=1000.

Card actions​

Cards may be dismissed, completed, or cancelled via this API. Typically card completion and dismissal occurs as customers interact with cards in their feed - for sanity of data we recommend cancelling cards via API rather than dismiss or completing unless you have specific use-cases in-mind.

Only cards in one of the following states may be dismissed or completed:

  • active
  • snoozed

Read more about possible card states in the Card lifecycle model.

Detailed specs and examples can be found in the Atomic API spec for the Cards API endpoint.

See our Cancel cards guide for a step-by-step guide on cancelling cards using Insomnia.

Last updated on