Skip to content

Create/Edit/Publish a Campaign

A consent campaign holds the descriptions of the campaign, associated rewards, and rules about how the consented data is shared. Please refer to campaign taxonomy for the structure of a campaign. When a campaign is created, it will be in draft state and you can edit before publishing it.

A campaign is created by sending a POST request to /v1/campaigns with a valid JWT. The body is a multipart/form-data that contains 2 objects:

Key Type Description
request application/json Required. Contains your consent campaign details
image multipart/form-data Optional. The header image of your campaign that is visible to data owners

request

title

The title of this campaign that is visible to the data owners. This is a required free text field.

reviewer

Optional. The email address of the reviewer from your organization, who will approve this campaign creation request.

protectionLevel

Optional. The level of encryption when a data recipient receives the data. Valid string values are:

  • "NONE"
  • "PASSWORD"
  • "AES"
  • "HOMOMORPHIC"

dataUsageDescription

Optional. The free text description for "Why do we use your data?" section, which is visible to data owners.

dataUsageDuration

The duration for which data will be shared.

dataUsageDurationUnit

The unit of the data usage duration. Valid string values are:

  • "Hours"
  • "Days"
  • "Months"
  • "Years"

datasets

datasourceId

The ID of the linked dataset.

columnNameEmailOwner

The column name of the data owner email field in the linked dataset. Consent requests will be sent to data owners at this email address.

payloads

Who can "see" the consented data and under what condition can each one of them "see" what data. The recipient can contain an organization_id or a group_id:

"payloads":[
   {"attributes":[
      {"path":"","fee":0},
      {"path":"","fee":0},
      {"path":"","fee":0}],
   "conditions":[{"column":"","operator":"","value":""}],
   "recipients":[{"recipient":""}]}]

Valid String values of "operator" are:

  • "EQUAL"
  • "DISTINCT"
  • "GREATER"
  • "LESS"

Here is an example "payloads" which allows anyone in the organization to receive 3 columns "TRANSACTIONS", "CATEGORY", "AMOUNT" from a dataset where "CATEGORY" is "Misc":

  "payloads": [{    
    "attributes": [
        {"path": "TRANSACTIONS"},
        {"path": "CATEGORY"},
        {"path": "AMOUNT"}],
    "conditions": [{"columnName": "CATEGORY","operator": "EQUAL","value": "Misc"}],
    "recipients": [{
        "recipient": ""}]}]

rewards

Optional. The rewards that data owner will receive if they consent to share data. 

rewards": [{
  "description": "string",
  "quantity": "string"
}]

showMetaData

  • "true"
  • "false".

If false, data owner will only see the name of the dataset in the consent request. If true, data owner will see the list of metadata in addition to the dataset name in the consent request.

image

Optional. A MultipartFile field. The image/logo that is displayed in the campaign.

Example

Here is an example of the request you would send to create a consent campaign.

Using a GET request to /v1/organizations//groups you can find the Id of groups you wish to share your policies with. Organization IDs can be found under user profile in the One Creation GUI. 

{
    "title": "",
    "protectionLevel": "AES",
    "reviewer":"",
    "dataUsageDescription": "",
    "dataUsageDuration": "1",
    "dataUsageDurationUnit": "Hours",
    "datasets": [
        {
            "datasetId": "",
            "columnNameEmailOwner": "EMAIL",
            "payloads": [
                {
                    "attributes": [
                        {
                            "path": "TRANSACTIONS"
                        },
                        {
                            "path": "CATEGORY"
                        },
                        {
                            "path": "AMOUNT"
                        }
                    ],
                    "conditions": [
                        {
                            "columnName": "CATEGORY",
                            "operator": "EQUAL",
                            "value": "Misc"
                        }
                    ],
                    "recipients": [
                        {
                            "recipient": ""
                        }
                    ]
                }
            ],
            "rewards": [
                {
                    "description": "dollars off monthly payments",
                    "quantity": "50"
                }
            ],
            "showMetaData": false
        }
    ]
}

Response

After the successful creation of a campaign, you will receive a success response with campaign "id".

If the creation of the campaign fails, you will receive a 4xx or 5xx error code with details in the response body. Please refer to this REST API Tutorial for the full list of all HTTP status codes.

Edit a Campaign

As soon as a campaign is created successfully, it's in draft mode. You can edit a draft campaign by sending a PUT request to /v1/campaigns/{campaignId}/edit with a valid JWT.

Publish a Campaign

You can publish a draft campaign to data owners by sending a POST request to /v1/campaigns/{campaignId}/publish with a valid JWT. As soon as a campaign is published successfully, all data owners will receive email notification with the consent request. You cannot edit a published campaign.

Approve/Reject a Create Campaign Request

If a reviewer is specified when creating a campaign, as soon as the campaign is created successfully, the reviewer receives an email notification to approve/reject the campaign. The reviewer can approve the campaign by sending a POST request to /v1/campaigns/{campaignId}/approve The reviewer can reject the campaign by sending a POST request to /v1/campaigns/{campaignId}/reject

Once a campaign is approved successfully, the campaign is automatically published.

Last update: May 18, 2023