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. This endpoint allows you to dismiss or complete cards programmatically as needed, for example when the card’s associated action is performed in your system, or cancel the card if it is no longer valid.

The same query attributes used for retrieving cards are used to action one or more cards.

Actioning multiple cards at once

Note, to action multiple cards at once, the query parameter multiple=1 must be passed. Without this parameter, the request will fail if more than one card matches the criteria.

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.

Dismiss​

Dismissed cards are removed from the customer’s feed. For example, to dismiss a single card that matches a lifecycleId:

curl -X PUT "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/cards/dismiss?lifecycleId=1234" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN"

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

Cancel​

Cancellation removes the card from the Atomic platform. For example, to cancel all cards for a given card template:

curl -X PUT "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/cards/cancel?cardTemplateId=abc" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN"

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

Complete​

When completing a card, a JSON payload can be sent corresponding to the completion state of the card.

The section on Data analytics preferences explains these two requirements to access this payload data:

  • The Configuration > Webhooks > Analytics Export Settings are set correctly for the environment.
  • You use the analytics API endpoints (read more about these in the Analytics guide), not the workbench analytics debugger to request this data.

For example, complete a single card that matches a lifecycle id with the following payload:

COMPLETE_PAYLOAD='{
    "quantity": 2,
    "size": "large"
}'

curl -X PUT "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/cards/complete?lifecycleId=1234" \
    --header "Content-Type:application/json" \
    --header "Authorization: Bearer $TOKEN" \
    --data $COMPLETE_PAYLOAD

The above query returns an array representing the actions performed on each card.

Example response:

{
  "data": [
    {
      "eventName": "",
      "eventSource": "live",
      "lifecycleId": "123",
      "cardTemplateId": "abc",
      "cardInstanceId": "456",
      "userId": "user_1",
      "action": "complete"
    }
  ],
  "summary": {
    "total": 1,
    "updated": 1
  }
}

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

Last updated on