Endpoint and Authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

This section of the documentation shows you how to customize and manage your Data Wallet.

Settings

List

GET /api/apps/app_identifier/data_wallet/settings

This API lists the language settings configured in the data wallet for a given app.

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to retrieve the data wallet language settings required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "languages": [
      {
        "identifier": "en",
        "label": "English"
      },
      {
        "identifier": "de",
        "label": "German"
      },
      {
        "identifier": "fr",
        "label": "French"
      }
    ]
  }
}

Update

PUT/PATCH /api/apps/app_identifier/data_wallet/settings

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to update the data wallet language settings required

Body Parameters

Property Type Description Default
languages array of objects The new set of languages for the data wallet required

Example

{
  "languages": [
  {
    "identifier": "en"
  },
  {
    "identifier": "de"
  },
  {
    "identifier": "fr"
  },
  {
    "identifier": "af"
  }
  ]
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
  "languages": [
    {
    "identifier": "en",
    "label": "English"
    },
    {
    "identifier": "de",
    "label": "German"
    },
    {
    "identifier": "fr",
    "label": "French"
    },
    {
    "identifier": "af",
    "label": "Afrikaans",
    }
  ]
  }
}

This sub-section shows you how to create and manage the legal texts of your data wallet.

List

GET /api/apps/app_identifier/data_wallet/legal_texts

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Response

Status: 200 OK

{
  "success": true,
  "result": [
  {
    "identifier": "FADWTEXT_1234567890654321",
    "technical_name": "legal_text_1",
    "title": {
    "en": "title 1",
    "de": "title 1",
    "fr": "title 1"
    },
    "text": {
    "en": "text 1",
    "de": "text 1",
    "fr": "text 1"
    }
  },
  {
    "identifier": "FADWTEXT_9876543210123456",
    "technical_name": "legal_text_2",
    "title": {
    "en": "title 2",
    "de": "title 2",
    "fr": "title 2"
    },
    "text": {
    "en": "text 2",
    "de": "text 2",
    "fr": "text 2"
    }
  }
  ]
}

Show

GET /api/apps/app_identifier/data_wallet/legal_texts/legal_text_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
legal_text_identifier string The identifier or technical_name of the legal text required

Response

Status: 200 OK

{
  "success": true,
  "result": {
  "identifier": "FADWTEXT_9876543210123456",
  "technical_name": "legal_text_2",
  "title": {
    "en": "title 2",
    "de": "title 2",
    "fr": "title 2"
  },
  "text": {
    "en": "text 2",
    "de": "text 2",
    "fr": "text 2"
  }
  }
}

Create

POST /api/apps/app_identifier/data_wallet/legal_texts

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the legal text. Can only contain lowercase letters and underscores. required
title object The title of the legal text in every desired language -
text object The text of the legal text in every desired language -

Example

{
  "technical_name": "test_legal_text",
  "title": {
    "en": "Test title",
    "de": "Test title",
    "fr": "Test title"
  },
  "text": {
    "en": "Test text",
    "de": "Test text",
    "fr": "Test text"
  }
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWTEXT_5k49DM0b9rlpEPmZ",
    "technical_name": "test_legal_text",
    "title": {
      "en": "Test title",
      "de": "Test title",
      "fr": "Test title"
    },
    "text": {
      "en": "Test text",
      "de": "Test text",
      "fr": "Test text"
    }
  }
}

Update

PUT/PATCH /api/apps/app_identifier/data_wallet/legal_texts/legal_text_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
legal_text_identifier string The identifier or technical_name of the legal text required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the legal text. Can only contain lowercase letters and underscores. -
title object The title of the legal text in every desired language -
text object The text of the legal text in every desired language -

Example

{
  "technical_name": "new_technical_name",
  "title": {
    "en": "New test title",
    "de": "New test title",
    "fr": "New test title"
  },
  "text": {
    "en": "New test text",
    "de": "New test text",
    "fr": "New test text"
  }
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWTEXT_5k49DM0b9rlpEPmZ",
    "technical_name": "new_technical_name",
    "title": {
      "en": "New test title",
      "de": "New test title",
      "fr": "New test title"
    },
    "text": {
      "en": "New test text",
      "de": "New test text",
      "fr": "New test text"
    }
  }
}

Delete

DELETE /api/apps/app_identifier/data_wallet/legal_texts/legal_text_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
legal_text_identifier string The identifier or technical_name of the legal text required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWTEXT_5k49DM0b9rlpEPmZ",
    "technical_name": "new_technical_name",
    "title": {
      "en": "New test title",
      "de": "New test title",
      "fr": "New test title"
    },
    "text": {
      "en": "New test text",
      "de": "New test text",
      "fr": "New test text"
    }
  }
}

Data Categories

This sub-section shows you how to create and manage the data categories of your data wallet.

List

GET /api/apps/app_identifier/data_wallet/categories

This API endpoint returns the default data categories defined by FollowAnalytics, in addition to all the custom ones created at any point.

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Response

Status: 200 OK

{
  "success": true,
  "result": [
    {
      "identifier": null,
      "technical_name": "usage",
      "title": {
        "en": "Usage data",
        "fr": "Données d'usage"
      },
      "description": {
        "en": "App environment information, sessions of usage, page views, actions and crashes",
        "fr": "Environnement de l'app, sessions d'utilisation, pages vues, actions et crashs"
      }
    },
    {
      "identifier": null,
      "technical_name": "push_notifications",
      "title": {
        "en": "Push notifications",
        "fr": "Notifications push"
      },
      "description": {
        "en": "Push notification permissions, preferences and token",
        "fr": "Permissions de notifications push, préférences et token."
      }
    },
    {
      "identifier": null,
      "technical_name": "user_profile",
      "title": {
        "en": "User profile",
        "fr": "Profil utilisateur"
      },
      "description": {
        "en": "User profile attributes",
        "fr": "Attributs du profil d'utilisateur"
      }
    },
    {
      "identifier": null,
      "technical_name": "geolocation",
      "title": {
        "en": "Geolocation",
        "fr": "Localisation utilisateur"
      },
      "description": {
        "en": "Sampling of GPS longitude and latitude of the device",
        "fr": "Longitude et latitude de l'appareil"
      }
    }
  ]
}

Show

GET /api/apps/app_identifier/data_wallet/categories/category_identifier

This API endpoint can also be used to show default data categories. However, for these you must call the API using their technical_name, because they have no identifier.

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
category_identifier string The identifier or technical_name of the data category required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": null,
    "technical_name": "usage",
    "title": {
      "en": "Usage data",
      "fr": "Données d'usage"
    },
    "description": {
      "en": "App environment information, sessions of usage, page views, actions and crashes",
      "fr": "Environnement de l'app, sessions d'utilisation, pages vues, actions et crashs"
    }
  }
}

Create

POST /api/apps/app_identifier/data_wallet/categories

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the data category. Can only contain lowercase letters and underscores. required
title object The title of the data category in every desired language -
description object The description of the data category in every desired language -

Example

{
  "technical_name": "test_category_1",
  "title": {
    "en": "test title 1",
    "fr": "test title 1"
  },
  "description": {
    "en": "test description 1",
    "fr": "test description 1"
  }
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWCAT_swxalEfeT-PwV50a",
    "technical_name": "test_category_1",
    "title": {
      "en": "test title 1",
      "fr": "test title 1"
    },
    "description": {
      "en": "test description 1",
      "fr": "test description 1"
    }
  }
}

Update

PUT/PATCH /api/apps/app_identifier/data_wallet/categories/category_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
category_identifier string The identifier or technical_name of the data category required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the data category. Can only contain lowercase letters and underscores. required
title object The title of the data category in every desired language -
description object The description of the data category in every desired language -

Example

{
  "technical_name": "test_category_1",
  "title": {
    "en": "new test title 1",
    "fr": "new test title 1"
  },
  "description": {
    "en": "new test description 1",
    "fr": "new test description 1"
  }
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWCAT_1234567890987654",
    "technical_name": "test_category_1",
    "title": {
      "en": "new test title 1",
      "fr": "new test title 1"
    },
    "description": {
      "en": "new test description 1",
      "fr": "new test description 1"
    }
  }
}

Note: If you try to modify a default data category, the request will fail.

Status: 405 Method Not Allowed

{
  "success": false,
  "status": 405,
  "error_message": "Cannot modify a static data category"
}

Delete

DELETE /api/apps/app_identifier/data_wallet/categories/category_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
category_identifier string The identifier or technical_name of the data category required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWCAT_swxalEfeT-PwV50a",
    "technical_name": "test_category_1",
    "title": {
      "en": "new test title 1",
      "fr": "new test title 1"
    },
    "description": {
      "en": "new test description 1",
      "fr": "new test description 1"
    }
  }
}

Note #1: If you try to delete a default data category, the request will fail.

Status: 405 Method Not Allowed

{
  "success": false,
  "status": 405,
  "error_message": "Cannot delete a static data category"
}

Note #2: Additionally, trying to delete a data category that is being used by a recipient will result in a request failure.

Status: 405 Method Not Allowed

{
  "success": false,
  "status": 405,
  "error_message": "Cannot delete a data category that is being used"
}

Recipients

This sub-section shows you how to create and manage the recipients of your data wallet.

List

GET /api/apps/app_identifier/data_wallet/recipients

This API endpoint returns our default FollowAnalytics recipient, in addition to all the custom ones created at any other point.

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Response

Status: 200 OK

{
  "success": true,
  "result": [
    {
      "technical_name": "followanalytics",
      "display_name": "FollowAnalytics",
      "count_data_elements": 55,
      "data_elements": [ ... ]
    },
    {
      "identifier": "FADWRECIPIENT_1234567890987654",
      "technical_name": "test_recipient_1",
      "display_name": "test recipient 1",
      "count_data_elements": 1,
      "data_elements": [
        {
          "technical_name": "test_element_1",
          "display_name": "test element 1",
          "data_category": {
              "technical_name": "usage",
              "title": {
                  "en": "Usage data",
                  "fr": "Données d'usage"
              }
          },
          "purposes": [ ... ]
        }
      ]
    }
  ]
}

Show

GET /api/apps/app_identifier/data_wallet/recipients/recipient_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
recipient_identifier string The identifier or technical_name of the recipient required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWRECIPIENT_1234567890987654",
    "technical_name": "test_recipient_1",
    "display_name": "test recipient 1",
    "count_data_elements": 1,
    "data_elements": [
      {
        "technical_name": "test_element_1",
        "display_name": "test_element_1",
        "data_category": {
          "technical_name": "usage",
          "title": {
            "en": "Usage data",
            "fr": "Données d'usage"
          }
        },
        "purposes": []
      }
    ]
  }
}

Create

POST /api/apps/app_identifier/data_wallet/recipients

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the recipient. Can only contain lowercase letters and underscores. required
display_name string The display name for the recipient required
data_elements array of objects The collection of data elements to create and associate to this recipient -

If the key data_elements is present, then the following apply per element in the array:

Property Type Description Default
data_element[technical_name] string A unique identifier for the data element. Can only contain lowercase letters and underscores. required
data_element[display_name] string The display name for the data element required
data_element[data_category] string The data category the element belongs to required
data_category[technical_name] string The technical name of the data category required

Example

{
  "technical_name": "test_recipient_1",
  "display_name": "test recipient 1",
  "data_elements": [
    {
      "technical_name": "test_element_1",
      "display_name": "test element 1",
      "data_category": {
        "technical_name": "usage"
      }
    }
  ]
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWRECIPIENT_rtMhONAmTfAjUtOt",
    "technical_name": "test_recipient_1",
    "display_name": "test recipient 1",
    "count_data_elements": 1,
    "data_elements": [
      {
        "technical_name": "test_element_1",
        "display_name": "test_element_1",
        "data_category": {
          "technical_name": "usage",
          "title": {
            "en": "Usage data",
            "fr": "Données d'usage"
          }
        },
        "purposes": []
      }
    ]
  }
}

Update

PUT/PATCH /api/apps/app_identifier/data_wallet/recipients/recipient_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
recipient_identifier string The identifier or technical_name of the recipient required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the recipient. Can only contain lowercase letters and underscores. required
display_name string The display name for the recipient required
data_elements array of objects The collection of data elements to create and associate to this recipient -

If the key data_elements is present, then the following apply per element in the array:

Property Type Description Default
data_element[technical_name] string A unique identifier for the data element. Can only contain lowercase letters and underscores. required
data_element[display_name] string The display name for the data element required
data_element[data_category] string The data category the element belongs to required
data_category[technical_name] string The technical name of the data category required

Example

{
    "display_name": "new test recipient 1",
  "data_elements": []
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWRECIPIENT_1234567890987654",
    "technical_name": "test_recipient_1",
    "display_name": "new test recipient 1",
    "count_data_elements": 0,
    "data_elements": []
  }
}

Note: If you try to modify a default recipient, the request will fail.

Status: 405 Method Not Allowed

{
  "success": false,
  "status": 405,
  "error_message": "You can not update a static Recipient"
}

Delete

DELETE /api/apps/app_identifier/data_wallet/recipients/recipient_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
recipient_identifier string The identifier or technical_name of the recipient required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWRECIPIENT_1234567890987654",
    "technical_name": "test_recipient_1",
    "display_name": "test recipient 1",
    "count_data_elements": 1,
    "data_elements": []
  }
}

Note: If you try to delete a default recipient, the request will fail.

Status: 405 Method Not Allowed

{
  "success": false,
  "status": 405,
  "error_message": "You can not delete a static Recipient"
}

Purposes

This sub-section shows you how to create and manage the purposes of your data wallet.

List

GET /api/apps/app_identifier/data_wallet/purposes

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Response

Status: 200 OK

{
  "success": true,
  "result": [
    {
      "identifier": "FADWPURP_1234567890987654",
      "technical_name": "test_purpose_1",
      "title": {
        "en": "test title 1",
        "fr": "test title 1",
      },
      "description": {
        "en": "test description 1",
        "fr": "test description 1",
      },
      "data_elements": [
        {
          "technical_name": "device_identifier",
          "display_name": "device_identifier",
          "recipient": {
            "technical_name": "followanalytics"
          },
          "data_category": {
            "technical_name": "usage"
          }
        }
      ]
    }
  ]
}

Show

GET /api/apps/app_identifier/data_wallet/purposes/purpose_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
purpose_identifier string The identifier or technical_name of the purpose required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWPURP_1234567890987654",
    "technical_name": "test_purpose_1",
    "title": {
      "en": "test title 1",
      "fr": "test title 1",
    },
    "description": {
      "en": "test description 1",
      "fr": "test description 1",
    },
    "data_elements": [
      {
        "technical_name": "device_identifier",
        "display_name": "device_identifier",
        "recipient": {
          "technical_name": "followanalytics"
        },
        "data_category": {
          "technical_name": "usage"
        }
      }
    ]
  }
}

Create

POST /api/apps/app_identifier/data_wallet/purposes

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the purpose. Can only contain lowercase letters and underscores. required
title object The title for the purpose in every desired language -
description object The description for the purpose in every desired language -
data_elements array of objects The collection of data elements to associate to this purpose -

If the key data_elements is present, then the following apply per element in the array:

Property Type Description Default
data_element[technical_name] string A unique identifier for the data element. Can only contain lowercase letters and underscores. required
data_element[display_name] string The display name for the data element required
data_element[recipient] string The recipient the element belongs to required
data_element[data_category] string The data category the element belongs to required
data_category[technical_name] string The technical name of the data category required

Example

{
  "technical_name": "test_purpose_1",
  "title": {
    "en": "test title 1",
    "fr": "test title 1",
  },
  "description": {
    "en": "test description 1",
    "fr": "test description 1",
  },
  "data_elements": [
    {
      "technical_name": "test_element_1",
      "display_name": "test_element_1",
      "recipient": {
        "technical_name": "followanalytics"
      },
      "data_category": {
        "technical_name": "usage"
      }
    }
  ]
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWPURP_1234567890987654",
    "technical_name": "test_purpose_1",
    "title": {
      "en": "test title 1",
      "fr": "test title 1",
    },
    "description": {
      "en": "test description 1",
      "fr": "test description 1",
    },
    "data_elements": [
      {
        "technical_name": "test_element_1",
        "display_name": "test_element_1",
        "recipient": {
          "technical_name": "followanalytics"
        },
        "data_category": {
          "technical_name": "usage"
        }
      }
    ]
  }
}

Update

PUT/PATCH /api/apps/app_identifier/data_wallet/purposes/purpose_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
purpose_identifier string The identifier or technical_name of the purpose required

Body Parameters

Property Type Description Default
technical_name string A unique identifier for the recipient. Can only contain lowercase letters and underscores. required
title object The title for the purpose in every desired language -
description object The description for the purpose in every desired language -
data_elements array of objects The collection of data elements to create and associate to this purpose -

If the key data_elements is present, then the following apply per element in the array:

Property Type Description Default
data_element[technical_name] string A unique identifier for the data element. Can only contain lowercase letters and underscores. required
data_element[display_name] string The display name for the data element required
data_element[data_category] string The data category the element belongs to required
data_category[technical_name] string The technical name of the data category required

Example

{
  "technical_name": "new_test_purpose_1",
    "title": {
    "en": "new test title 1",
    "fr": "new test title 1"
  },
  "description": {
    "en": "new test description 1",
    "fr": "new test description 1"
  },
  "data_elements": [],
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWPURP_1234567890987654",
    "technical_name": "new_test_purpose_1",
    "title": {
      "en": "new test purpose 1",
      "fr": "new test purpose 1"
    },
    "description": {
      "en": "new test description 1",
      "fr": "new test description 1"
    },
    "data_elements": []
  }
}

Delete

DELETE /api/apps/app_identifier/data_wallet/purposes/purpose_identifier

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
purpose_identifier string The identifier or technical_name of the purpose required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "identifier": "FADWPURP_1234567890987654",
    "technical_name": "new_test_purpose_1",
    "title": {
      "en": "new test title 1",
      "fr": "new test title 1"
    },
    "description": {
      "en": "new test description 1",
      "fr": "new test description 1"
    },
    "data_elements": []
  }
}

Policies

This sub-section shows you how to check for changes in your data wallet policy as well as how to publish new versions of the policy. Additionally, you can choose to download and view each policy version.

List

GET /api/apps/app_identifier/data_wallet/policies

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Response

Status: 200 OK

{
    "success": true,
    "result": [
        {
            "version": "1.0",
            "major": true,
            "published_at": "2018-05-14T09:24:20Z",
            "changes": 24,
            "languages": {
                "en": {...}, // English policy changes here
                "de": {...}, // German policy changes here
                "fr": {
                    "title": "French",
                    "legal_texts": {
                        "test_legal_text_1": {
                            "title": "test title 1",
                            "text": "test text 1"
                        }
                    },
                    "categories": {
                        "geolocation": {
                            "title": "Localisation utilisateur",
                            "description": "Longitude et latitude de l'appareil"
                        },
                        "push_notifications": {
                            "title": "Notifications push",
                            "description": "Permissions de notifications push, préférences et token."
                        },
                        "usage": {
                            "title": "Données d'usage",
                            "description": "Environnement de l'app, sessions d'utilisation, pages vues, actions et crashs"
                        },
                        "user_profile": {
                            "title": "Profil utilisateur",
                            "description": "Attributs du profil d'utilisateur"
                        },
                        "test_category_1": {
                            "title": "test category 1",
                            "description": "test category description 1"
                        }
                    },
                    "recipients": {
                        "followanalytics": {
                            "title": "FollowAnalytics",
                            "categories": {
                                "usage": {
                                    "title": "Données d'usage",
                                    "data_elements": {...}
                                },
                                "user_profile": {
                                    "title": "Profil utilisateur",
                                    "data_elements": {...}
                                },
                                "geolocation": {
                                    "title": "Localisation utilisateur",
                                    "data_elements": {...}
                                },
                                "push_notifications": {
                                    "title": "Notifications push",
                                    "data_elements": {...}
                                }
                            },
                            "data_elements": {...}
                        }
                    },
                    "purposes": {
                        "test_purpose_1": {
                            "title": "test title 1",
                            "description": "test description 1",
                            "categories": {
                                "test_category_1": {
                                    "title": "test category 1"
                                }
                            },
                            "recipients": {
                                "followanalytics": {
                                    "title": "FollowAnalytics",
                                    "data_elements": {...}
                                }
                            }
                        }
                    }
                }
            }
        }
    ]
}

Show

GET /api/apps/app_identifier/data_wallet/policies/policy_version

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
policy_version string The version of the policy that you want to view (e.g. 1.1, 2.0, 3.2, etc.). You may also use the keywords latest or draft. By passing latest as policy version, this endpoint will fetch the latest published policy. By passing draft, it will fetch the current unpublished policy. required

Response

Status: 200 OK

{
    "success": true,
    "result": {
        "version": "2.0",
        "major": true,
        "published_at": "2018-05-15T10:00:17Z",
        "changes": 16,
        "languages": {
            "en": {...}, // English policy changes here
            "fr": {
                "title": "French",
                "legal_texts": {},
                "categories": {
                    "geolocation": {
                        "title": "Localisation utilisateur",
                        "description": "Longitude et latitude de l'appareil"
                    },
                    "push_notifications": {
                        "title": "Notifications push",
                        "description": "Permissions de notifications push, préférences et token."
                    },
                    "usage": {
                        "title": "Données d'usage",
                        "description": "Environnement de l'app, sessions d'utilisation, pages vues, actions et crashs"
                    },
                    "user_profile": {
                        "title": "Profil utilisateur",
                        "description": "Attributs du profil d'utilisateur"
                    }
                },
                "recipients": {
                    "followanalytics": {
                        "title": "FollowAnalytics",
                        "categories": {
                            "usage": {
                                "title": "Données d'usage",
                                "data_elements": {...}
                            },
                            "user_profile": {
                                "title": "Profil utilisateur",
                                "data_elements": {...}
                            },
                            "geolocation": {
                                "title": "Localisation utilisateur",
                                "data_elements": {...}
                            },
                            "push_notifications": {
                                "title": "Notifications push",
                                "data_elements": {...}
                            }
                        },
                        "data_elements": {...}
                    },
                    "test_recipient_1": {
                        "title": "test recipient 1",
                        "categories": {
                            "usage": {
                                "title": "Données d'usage",
                                "data_elements": {...}
                            }
                        },
                        "data_elements": {...}
                    }
                },
                "purposes": {
                    "test_purpose_1": {
                        "title": "test purpose 1",
                        "description": "test description 1",
                        "categories": {
                            "geolocation": {
                                "title": "Localisation utilisateur"
                            },
                            "push_notifications": {
                                "title": "Notifications push"
                            }
                        },
                        "recipients": {
                            "followanalytics": {
                                "title": "FollowAnalytics",
                                "data_elements": {...}
                            }
                        }
                    }
                }
            }
        }
    }
}

Note: If the policy version specified in the query parameters does not exist, the request will fail.

Status: 404 Not Found

{
  "success": false,
  "status": 404,
  "error_message": "Policy version '1.5' not found"
}

Changes

GET /api/apps/app_identifier/data_wallet/policies/changes

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "changes": 16,
    "legal_texts_valid": false,
    "categories_valid": true,
    "recipients_valid": true,
    "purposes_valid": true,
    "valid": false
  }
}

Diff

GET /api/apps/app_identifier/data_wallet/policies/diff?old=old_version&new=new_version

This endpoint returns the differences between two specified policies. If no specific versions are given, then it will compare the current unpublished policy with the latest published one (previous policy).

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
old_version string The first policy version to use in the comparation. Default is previous, which is the most recent published version. previous
new_version string The second policy version to use in the comparation. Default is draft, which is the current unpublished version. draft

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "languages": {
      "en": {
        "title": "English",
        "change": "modified",
        "changes": 1,
        "legal_texts": {
          "test_legal_text_1": {
            "title": {
              "old": "",
              "new": "<ins>test legal text 1</ins>"
            },
            "text": {
              "old": "",
              "new": "<ins>test legal text 1</ins>"
            },
            "change": "added"
          }
        },
        "categories": {},
        "recipients": {},
        "purposes": {}
      }
    },
    "changes": 1
  }
}

Publish

POST /api/apps/app_identifier/data_wallet/policies/publish/version_type

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
version_type string The type of the version to be published. Can be either major or minor required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "version": "1.0",
    "major": true,
    "published_at": "2018-05-15T13:41:32Z",
    "changes": 10,
    "languages": {
      "en": {
        "title": "English",
        "legal_texts": {},
        "categories": {
          "geolocation": {
            "title": "Geolocation",
            "description": "Sampling of GPS longitude and latitude of the device"
          },
          "push_notifications": {
            "title": "Push notifications",
            "description": "Push notification permissions, preferences and token"
          },
          "usage": {
            "title": "Usage data",
            "description": "App environment information, sessions of usage, page views, actions and crashes"
          },
          "user_profile": {
            "title": "User profile",
            "description": "User profile attributes"
          }
        },
        "recipients": {
          "followanalytics": {
            "title": "FollowAnalytics",
            "categories": {
              "usage": {
                "title": "Usage data",
                "data_elements": {...}
              },
              "user_profile": {
                "title": "User profile",
                "data_elements": {...}
              },
              "geolocation": {
                "title": "Geolocation",
                "data_elements": {...}
              },
              "push_notifications": {
                "title": "Push notifications",
                "data_elements": {...}
              }
            },
            "data_elements": {...}
          }
        },
        "purposes": {}
      }
    }
  }
}

Note #1: If the current unpublished policy is not valid, then this request will fail.

Status: 400 Bad Request

{
    "success": false,
    "status": 400,
    "messages": [
        {
            "element": "legal_texts.test_legal_text_1.text",
            "severity": "error",
            "message": "Text is missing in English"
        }
    ],
    "errors": [
        "Text Text is missing in English"
    ],
    "error_message": "Text is missing in English"
}

Note #2: If the version_type specified is neither major or minor, then the request will also fail.

Status: 400 Bad Request

{
  "success": false,
  "status": 400,
  "error_message": "Unknown version type"
}

Download

GET /api/apps/app_identifier/data_wallet/policies/policy_version/download?version=version

Query Parameters

Property Type Description Default
app_identifier string The identifier of the app to fetch the data wallet required
version string The policy version to download. Can be either latest or a specific version number. latest

Response

Status: 200 OK

{
    "indent": 2,
    "success": true,
    "result": {
        "version": "1.0",
        "major": true,
        "published_at": "2018-05-15T13:41:32Z",
        "changes": 10,
        "languages": {
            "en": {
                "title": "English",
                "legal_texts": {},
                "categories": {
                    "geolocation": {
                        "title": "Geolocation",
                        "description": "Sampling of GPS longitude and latitude of the device"
                    },
                    "push_notifications": {
                        "title": "Push notifications",
                        "description": "Push notification permissions, preferences and token"
                    },
                    "usage": {
                        "title": "Usage data",
                        "description": "App environment information, sessions of usage, page views, actions and crashes"
                    },
                    "user_profile": {
                        "title": "User profile",
                        "description": "User profile attributes"
                    }
                },
                "recipients": {
                    "followanalytics": {
                        "title": "FollowAnalytics",
                        "categories": {
                            "usage": {
                                "title": "Usage data",
                                "data_elements": {...}
                            },
                            "user_profile": {
                                "title": "User profile",
                                "data_elements": {...}
                            },
                            "geolocation": {
                                "title": "Geolocation",
                                "data_elements": {...}
                            },
                            "push_notifications": {
                                "title": "Push notifications",
                                "data_elements": {...}
                            }
                        },
                        "data_elements": {...}
                    }
                },
                "purposes": {}
            }
        }
    }
}

Note #1: If the version specified is draft, the request will fail.

Status: 400 Bad Request

{
  "success": false,
  "status": 400,
  "error_message": "Cannot download a draft version"
}

Note #1: If the version specified does not exist, the request will also fail.

Status: 404 Not Found

{
  "success": false,
  "status": 404,
  "error_message": "Policy version '4.3' not found"
}