Skip to main content

The Challenges API

Caution

Challenges is currently in closed beta and any part could change before the full release. Contact your account manager at Voyado if you want to try it out.

There are three different IDs to keep in mind when working with the challenges API:

  • Contact ID: This is the usual Engage contact ID, used to uniquely identify a contact,

  • Definition ID: The definition of a challenge, meaning its basic structure or template, has a unique definition ID. From when it's created to when it's destroyed, the challenge definition will have the same definition ID.

  • Challenge ID: Assigning a challenge definition to a contact creates a specific "instance" of that definition, which then belongs to that contact. This instance is called a challenge, and is given a unique challenge ID. Each challenge ID is therefore uniquely connected to one contact ID and one definition ID.

The challenges API

The challenges API consists of 6 endpoints. Here's a quick overview of what they do. Further down you'll find a more detailed look at each one.

  • GET /api/v2/challenges

    Fetches all of a specific contact's assigned challenges, with different ways to filter the results.

  • GET /api/v2/challenges/{id}

    Fetches a specific assigned challenge for a contact by its challenge ID.

  • POST /api/v2/challenges/checkpoints

    Awards a number of checkpoints in some contact's challenge (can be batched).

  • GET /api/v2/challenges/definitions

    Fetches a list of all the challenge definitions in your environment.

  • GET /api/v2/challenges/definitions/{id}

    Fetches a specific challenge definition by its unique ID.

  • POST /api/v2/challenges/definitions/{id}/activate

    Assigns and activates a challenge for a contact from the given definition ID.

Get challenges for a specific contact

Use this endpoint to get all of a contact's challenges, even the completed ones.

GET /api/v2/challenges

The parameter contactId for the contact is required here.

The optional parameter definitionId can be added to restrict the results to only that challenge definition.

The optional parameters offset and count can be used to paginate the results.

The optional parameter filter can be used to narrow the results to "All", "Active", "Completed" or "NotCompleted".

All the above parameters are added to the query string.

Get an assigned challenge from its challenge ID

Use this endpoint to get the full details of an assigned challenge, including the contact's progress, using the challenge ID. A challenge is only connected to one contact, so the contact ID is not required in the request.

GET /api/v2/challenges/{id}

The response will look something like this:

{
  "challengeId": "081225de-8a42-45f8-a3b7-03d9c97ee19c",
  "challengeStart": "2023-09-21T10:52:38.2535557+02:00",
  "completedCheckpoints": 2,
  "contactId": "2285d25b-622c-45ce-bc13-fccdd1147d4d",
  "id": "3a4a81c3-ea2c-4f4c-866b-6dcadf257759",
  "isActive": false,
  "isChallengeCompleted": false,
  "latestCheckpointAddedOn": "2023-09-26T10:52:38.2535557+02:00",
  "requiredCheckpoints": 5,
  "status": 3,
  "links": [
    {
      "id": "3a4a81c3-ea2c-4f4c-866b-6dcadf257759",
      "href": "https://yoururl/api/v2/challenges/3a4a81c3-ea2c-4f4c-866b-6dcadf257759",
      "method": "GET",
      "rel": "self"
    },
    {
      "id": "081225de-8a42-45f8-a3b7-03d9c97ee19c",
      "href": "https://yoururl/api/v2/challenges/definitions/081225de-8a42-45f8-a3b7-03d9c97ee19c",
      "method": "GET",
      "rel": "definition"
    }
  ]
}

Add checkpoints in a certain challenge for a contact (one or many)

Use this endpoint to add to a contact's progress through a specific challenge. The definitionId of the challenge and the contactId must be sent in the payload, along with the number of checkpoints to be added. Updates to several contacts can be batched in the same request.

POST /api/v2/challenges/checkpoints

The payload is sent in the body of the query as follows:

[
  {
    "definitionId": "bbf8d0a3-7057-4b21-9fd1-a9ba21116d5c",
    "contactId": "96465573-53e7-453f-a2d9-fa65a68de111",
    "checkpointAmount": 1
  }, 
  {
    "definitionId": "bbf8d0a3-7057-4b21-9fd1-a9ba21116d5c",
    "contactId": "63706fea-10d9-459e-a78a-1011486fb46f",
    "checkpointAmount": 2
  },
  {
    "definitionId": "2b84e222-2f84-4553-a775-7755ea912e52",
    "contactId": "be541846-34e2-4bb2-b693-b4c5a31c27b9",
    "checkpointAmount": 1
  }
]

If something is incorrect it will still result in an accepted response code, but that block will be skipped. Engage will continue to process the next block. The HTTP 200 OK response will have details of the error, like this:

{
  "missingContactIds": [
    "a311f9f9-9bdc-4b85-9f6c-b269ab204038"
  ],
  "missingDefinitionIds": [
    "4524db0c-4d43-417e-b437-d75ca2cda3a6"
  ],
  "notAccepted": [
    {
      "definitionId": "4524db0c-4d43-417e-b437-d75ca2cda3a6",
      "contactId": "aace6d91-3f0f-472e-9583-b9e5c4acbaa1",
      "checkpointAmount": 2
    },
    {
      "definitionId": "0c469396-d94d-4f86-934d-244d6080c353",
      "contactId": "a311f9f9-9bdc-4b85-9f6c-b269ab204038",
      "checkpointAmount": 1
    }
  ]
}

Get a list of all the challenge definitions

This returns a list of all challenge definitions in your Engage environment.

GET /api/v2/challenges/definitions

The results can be paginated using the optional parameters count and offset, as well as filtered by status which can have the values "All" (the default) as well as "Active", "Draft", "Scheduled" or "Ended".

A successful request will return something like this:

{
  "links": [
    {
      "href": "",
      "method": "GET",
      "rel": "previous"
    },
    {
      "href": "",
      "method": "GET",
      "rel": "next"
    }
  ],
  "count": 1,
  "offset": 0,
  "items": [
    {
      "checkpointAssignOn": 2,
      "checkpointAssignOnAmount": 1,
      "createdBy": "Joe Doe",
      "createdOn": "2023-07-08T09:21:39.9997785+02:00",
      "description": "Buy 5 get one for free",
      "expirationMonths": 5,
      "id": "74bb66f1-6993-442e-bb93-e41e1ecc3184",
      "isContactConsentRequired": false,
      "isScheduled": false,
      "modifiedBy": "Jane Doe",
      "modifiedOn": "2023-07-18T09:21:39.9997785+02:00",
      "name": "Dog food",
      "requiredNumberOfCheckpoints": 5,
      "status": 1,
      "links": []
    }
  ],
  "totalCount": 1
}

Every object in the "items" array is a challenge definition.

Get a specific challenge definition by its ID

This returns a specific challenge definition based on its unique definition ID.

GET /api/v2/challenges/definitions/{id}

The response is essentially a single object from the "items" array of the previous endpoint (see the data example).

Activate a specific challenge for a contact

This creates an assignment of a specific challenge for a specific contact and activates it with a checkpoint count of zero.

POST /api/v2/challenges/definitions/{id}/activate

The definitionId is sent in the request path and contactId is sent in the query string. A HTTP 200 OK response with the value of "true" will be returned if the assignment was created (or if it already exists).

Note

A challenge is configured so that the contact has to give their consent to be included. To activate the challenge for a contact, call this endpoint. It's up to the retailer and their internal process to decide when a challenge can and should be activated for a contact.

In this section: