# Dataguard Preferences Documentation > Use Dataguard Preference Management software to manage customer marketing permissions, consents and preferences to help maximise engagement. Optimise customer permissions. Put your customers first in everything you do. Dataguard can help you improve customer engagement and privacy regulation compliance. ## Guides - [Introduction](https://docs-cpm.dataguard.com/docs/introduction.md) - [Key Concepts](https://docs-cpm.dataguard.com/docs/key-concepts.md) - [Consent Workflow](https://docs-cpm.dataguard.com/docs/consent-workflow.md) - [Form Builder](https://docs-cpm.dataguard.com/docs/form-builder.md) - [Integrations](https://docs-cpm.dataguard.com/docs/integrations-overview.md) - [✅ Consent Framework Quick Start](https://docs-cpm.dataguard.com/docs/consent-framework-quick-start.md) - [1. Create Your First Consent Purpose](https://docs-cpm.dataguard.com/docs/create-your-first-consent-purpose.md) - [2. Upload a Privacy Policy](https://docs-cpm.dataguard.com/docs/upload-a-privacy-policy.md) - [3. Build a Consent Form](https://docs-cpm.dataguard.com/docs/build-a-consent-form.md) - [4. Start Collecting Consent](https://docs-cpm.dataguard.com/docs/start-collecting-consent.md) - [5. Set Up an Integration](https://docs-cpm.dataguard.com/docs/set-up-an-integration.md) - [🙋 Manage Citizens in the UI](https://docs-cpm.dataguard.com/docs/manage-citizens-in-the-ui.md) - [Record Consent](https://docs-cpm.dataguard.com/docs/record-consent.md) - [Record Preferences](https://docs-cpm.dataguard.com/docs/record-preferences.md): How to use our UI to capture preferences - [Check the Audit Trail](https://docs-cpm.dataguard.com/docs/check-the-audit-trail.md) - [💻 Implement Technical Integrations](https://docs-cpm.dataguard.com/docs/implement-technical-integrations.md) - [Using the Sign Up Widget](https://docs-cpm.dataguard.com/docs/using-the-sign-up-widget.md) - [Using the Manage Widget](https://docs-cpm.dataguard.com/docs/using-the-manage-widget.md) - [Create a Mobile Integration](https://docs-cpm.dataguard.com/docs/create-a-mobile-integration.md) - [Custom Backend Integration](https://docs-cpm.dataguard.com/docs/custom-backend-integration.md) - [📈 Increase Opt-In Rates](https://docs-cpm.dataguard.com/docs/increase-opt-in-rates.md) - [Tailor Communication with Preferences](https://docs-cpm.dataguard.com/docs/tailor-communication-with-preferences.md) - [A/B Testing with Campaigns](https://docs-cpm.dataguard.com/docs/ab-testing-with-campaigns.md) - [Increase Engagement with Progressive Consent](https://docs-cpm.dataguard.com/docs/increase-engagement-with-progressive-consent.md) - [Product Breakdown](https://docs-cpm.dataguard.com/docs/product-breakdown.md) - [Citizens](https://docs-cpm.dataguard.com/docs/citizens.md) - [Citizen Email Addresses](https://docs-cpm.dataguard.com/docs/citizen-email-addresses.md) - [Linking Citizens](https://docs-cpm.dataguard.com/docs/linking-citizens.md) - [Merging Citizens](https://docs-cpm.dataguard.com/docs/merging-citizens.md) - [Duplicating Citizens](https://docs-cpm.dataguard.com/docs/duplicating-citizens.md) - [Consent](https://docs-cpm.dataguard.com/docs/consent.md) - [Consent Purposes](https://docs-cpm.dataguard.com/docs/consent-purposes.md) - [Permissions](https://docs-cpm.dataguard.com/docs/permissions.md) - [Transactions](https://docs-cpm.dataguard.com/docs/transactions.md) - [Default Permissions](https://docs-cpm.dataguard.com/docs/claim-default-permissions.md) - [Double Opt-In](https://docs-cpm.dataguard.com/docs/double-opt-in.md) - [Privacy Policies](https://docs-cpm.dataguard.com/docs/privacy-policies.md) - [Permission Statements](https://docs-cpm.dataguard.com/docs/permission-statements.md) - [Objection Management](https://docs-cpm.dataguard.com/docs/objection-management.md) - [Preferences](https://docs-cpm.dataguard.com/docs/preferences.md) - [Preference Configuration](https://docs-cpm.dataguard.com/docs/preference-configuration.md) - [Preference State](https://docs-cpm.dataguard.com/docs/preference-state.md) - [Submissions](https://docs-cpm.dataguard.com/docs/submissions.md) - [Widgets](https://docs-cpm.dataguard.com/docs/widgets.md) - [Templates](https://docs-cpm.dataguard.com/docs/templates.md) - [Branding](https://docs-cpm.dataguard.com/docs/branding.md) - [Rule Sets](https://docs-cpm.dataguard.com/docs/rule-sets.md) - [Hosted Preference Centres](https://docs-cpm.dataguard.com/docs/hosted-preference-centres.md) - [Localisation](https://docs-cpm.dataguard.com/docs/localisation.md) - [Analytics](https://docs-cpm.dataguard.com/docs/analytics.md) - [Dashboard](https://docs-cpm.dataguard.com/docs/dashboard.md) - [Campaigns](https://docs-cpm.dataguard.com/docs/campaigns.md) - [Web Integrations](https://docs-cpm.dataguard.com/docs/web-integrations.md) - [Sign Up Widget](https://docs-cpm.dataguard.com/docs/sign-up-widget.md) - [Manage Widget](https://docs-cpm.dataguard.com/docs/manage-widget.md) - [History Widget](https://docs-cpm.dataguard.com/docs/history-widget.md) - [Customise Widget Styling](https://docs-cpm.dataguard.com/docs/customise-widget-styling.md) - [Citizen Tokens](https://docs-cpm.dataguard.com/docs/citizen-tokens.md) - [Mobile Integrations](https://docs-cpm.dataguard.com/docs/mobile-integrations.md) - [Native Mobile Integration](https://docs-cpm.dataguard.com/docs/native-mobile-integration.md) - [Webview Mobile Integration](https://docs-cpm.dataguard.com/docs/webview-mobile-integration.md) - [Android App Webview](https://docs-cpm.dataguard.com/docs/android-app-webview.md) - [iOS App Webview](https://docs-cpm.dataguard.com/docs/ios-app-webview.md) - [Marketplace Integrations](https://docs-cpm.dataguard.com/docs/marketplace-integrations.md) - [CRMs](https://docs-cpm.dataguard.com/docs/crm.md) - [Salesforce](https://docs-cpm.dataguard.com/docs/salesforce.md) - [HubSpot](https://docs-cpm.dataguard.com/docs/hubspot.md) - [Dynamics](https://docs-cpm.dataguard.com/docs/dynamics.md) - [Marketing Automation](https://docs-cpm.dataguard.com/docs/marketing-automation.md) - [Braze](https://docs-cpm.dataguard.com/docs/braze.md) - [Brevo](https://docs-cpm.dataguard.com/docs/brevo.md) - [Mailchimp](https://docs-cpm.dataguard.com/docs/mailchimp.md) - [Salesforce Marketing Cloud](https://docs-cpm.dataguard.com/docs/salesforce-marketing-cloud.md) - [Identity Providers](https://docs-cpm.dataguard.com/docs/identity-providers.md) - [Auth0](https://docs-cpm.dataguard.com/docs/auth0.md) - [Ping Identity](https://docs-cpm.dataguard.com/docs/ping-identity.md) - [Data Warehouses](https://docs-cpm.dataguard.com/docs/data-warehouses.md) - [Snowflake](https://docs-cpm.dataguard.com/docs/snowflake.md) - [SMTP](https://docs-cpm.dataguard.com/docs/smtp.md) - [Form Builders](https://docs-cpm.dataguard.com/docs/form-builders.md) - [Braze In-App Campaigns](https://docs-cpm.dataguard.com/docs/braze-in-app-campaigns.md) - [Brevo Forms](https://docs-cpm.dataguard.com/docs/brevo-forms.md) - [FormAssembly](https://docs-cpm.dataguard.com/docs/formassembly.md) - [Formstack](https://docs-cpm.dataguard.com/docs/formstack.md) - [Wordpress Contact Form 7](https://docs-cpm.dataguard.com/docs/wordpress-contact-form-7.md) - [Build Your Own Integration](https://docs-cpm.dataguard.com/docs/build-your-own-integration.md) - [API Integrations](https://docs-cpm.dataguard.com/docs/api-integrations.md) - [API Authentication](https://docs-cpm.dataguard.com/docs/api-authentication.md) - [Environments](https://docs-cpm.dataguard.com/docs/environments.md) - [Postman Collection](https://docs-cpm.dataguard.com/docs/postman-collection.md) - [Webhooks](https://docs-cpm.dataguard.com/docs/webhooks.md) - [Data Export](https://docs-cpm.dataguard.com/docs/data-export.md) - [Data Import](https://docs-cpm.dataguard.com/docs/data-import.md) - [Data Deletion](https://docs-cpm.dataguard.com/docs/data-deletion.md) - [Single Sign-On](https://docs-cpm.dataguard.com/docs/single-sign-on.md) - [Azure Active Directory (AD)](https://docs-cpm.dataguard.com/docs/azure-active-directory.md) - [Security Assertion Markup Language (SAML)](https://docs-cpm.dataguard.com/docs/security-assertion-markup-language-saml.md) - [OpenID Connect (OIDC)](https://docs-cpm.dataguard.com/docs/openid-connect-oidc.md) ## API Reference - [Updates a new Data List Item by Id](https://docs-cpm.dataguard.com/reference/updatedatalist.md) - [Fetches a single Data List Item by Id](https://docs-cpm.dataguard.com/reference/getdatalist.md) - [Deletes a Data List Item by Id](https://docs-cpm.dataguard.com/reference/deletedatalist.md) - [Creates a new Data List Item](https://docs-cpm.dataguard.com/reference/createdatalist.md) - [Free-form search across properties in the lists](https://docs-cpm.dataguard.com/reference/getdatalists.md): This query allows searching by any property of the items in the list. Top-level properties such as display_name, external_reference and category are supported. It also supports the property names inside the properties array (provided the name doesn't match a top-level property). These property names will differ from list to list, and so cannot be defined in advance. All matches are partial, e.g. a query parameter of privacyPolicyRef=nov will match items with entries in the property array under key privacyPolicyRef having values of 'nov2017', 'nov17', or 'november_2017'. Hence, passing in an empty string will match items with any value for a given key. - [Updates a new Data List Item by Reference](https://docs-cpm.dataguard.com/reference/updatedatalistbyref.md) - [Fetches a single Data List Item by Reference](https://docs-cpm.dataguard.com/reference/getdatalistbyref.md) - [Deletes a Data List Item by Reference](https://docs-cpm.dataguard.com/reference/deletedatalistbyref.md) - [Get audit information](https://docs-cpm.dataguard.com/reference/getobjectionconfigurationauditinfo.md) - [Get an Objection Configuration](https://docs-cpm.dataguard.com/reference/getobjectionconfiguration.md) - [Updates an Objection Configuration](https://docs-cpm.dataguard.com/reference/updateobjectionconfiguration.md) - [Creates an Objection Configuration](https://docs-cpm.dataguard.com/reference/createobjectionconfiguration.md) - [Get Objection Configuration for an application](https://docs-cpm.dataguard.com/reference/getobjectionconfigurations.md) - [Get filtered objections for an Application Id](https://docs-cpm.dataguard.com/reference/getobjections.md) - [Get audit information for a given objection](https://docs-cpm.dataguard.com/reference/getobjectionauditinfo.md) - [Update an objection](https://docs-cpm.dataguard.com/reference/updateobjection.md) - [Creates a Statement Link](https://docs-cpm.dataguard.com/reference/createstatementlink.md): The provided reference field must be unique. - [Retrieves Statement Links.](https://docs-cpm.dataguard.com/reference/retrievestatementlinkforapplication.md) - [Retrieves Statement Link by Reference](https://docs-cpm.dataguard.com/reference/retrievestatementlinkbyapplicationidandreference.md) - [Updates a Statement Link](https://docs-cpm.dataguard.com/reference/updatestatementlink.md): Both name and permissionStatementId must be provided. The name field will replace the existing name, the permissionStatementId field will point the Statement Link to a new Permission Statement. - [Patches a Statement Link](https://docs-cpm.dataguard.com/reference/patchstatementlink.md) - [Creates a Permission Statement](https://docs-cpm.dataguard.com/reference/createpermissionstatement.md): The provided statementRef field must be unique. - [Retrieves Permission Statements.](https://docs-cpm.dataguard.com/reference/retrievepermissionstatementsforapplication.md): This endpoint is paginated via the limit and offset parameters. - [Updates a Permission Statement status](https://docs-cpm.dataguard.com/reference/updatepermissionstatementstatus.md) - [Retrieves Permission Statement by ID](https://docs-cpm.dataguard.com/reference/retrievepermissionstatementbyid.md) - [Retrieve a citizen's 'effective' permissions for the given arguments](https://docs-cpm.dataguard.com/reference/getpermissions.md): The request MUST provide either `citizenId` or `externalRef` or both. If both `citizenId` and `externalRef` are provided, they must resolve to the same Citizen. If the validity range (`validStart` to `validEnd`) is omitted, the server timestamp will be used for both. If only `validStart` is provided, then the validity range will be from `validStart` until now. If only `validEnd` is provided, then the validity range will be from now until `validEnd`. Only permissions that are valid from the start and still valid at the end of the range will be returned. Permissions without a `validUntil` date will be considered valid from their start date until the end of time. - [Retrieves effective Permissions and Preferences for an Application.](https://docs-cpm.dataguard.com/reference/getalleffectivepermissionsv2.md): Full content information for the `permissions` and `preferences` response fields can be found under #/Permissions/getPermissionsV2 and #/Preferences/getPreferences respectively. Note that this endpoint will return records ordered by their createdAt date, not by their updatedAt date. - [Retrieves effective Permissions and Preferences for an Application.](https://docs-cpm.dataguard.com/reference/getalleffectivepermissions.md): Full content information for the `permissions` and `preferences` response fields can be found under #/Permissions/getPermissionsV2 and #/Preferences/getPreferences respectively. When a value for `externalRef` is provided, pagination fields are ignored. For optimum performance, it is recommended that the `includeTotal` parameter is set to `false` unless the value of the `total` field in the response is absolutely necessary. For backwards compatibility, it defaults to `true`. In the event of receiving a response with status code 504 (GATEWAY TIMEOUT), it is recommended that the `since` and `before` parameters are used to reduce the quantity of data to be paginated. Multiple smaller date ranges can be used to traverse larger periods. - [Update a Privacy Policy](https://docs-cpm.dataguard.com/reference/updateprivacypolicyv2.md) - [Get a Privacy Policy by its Id](https://docs-cpm.dataguard.com/reference/getprivacypolicybyidv2.md) - [Create a Policy Permit](https://docs-cpm.dataguard.com/reference/createprivacypolicypermit.md): The Permit will provide an Upload URL to which a Privacy Policy file can be uploaded. A PUT request to the Upload URL will require an `x-ms-blob-type: BlockBlob` header to be successful. - [Create a Privacy Policy](https://docs-cpm.dataguard.com/reference/createprivacypolicyv2.md) - [Get Privacy Policies](https://docs-cpm.dataguard.com/reference/getprivacypoliciesv2.md) - [Register an Externally Managed Privacy Policy](https://docs-cpm.dataguard.com/reference/registerprivacypolicyv2.md) - [Submit updated Consent State for a Citizen](https://docs-cpm.dataguard.com/reference/postconsentstate.md): In order to update the Permissions and Preferences of a data subject, simply submit an Enriched Template with the corresponding values. If the request returns a 2xx response code, the permissions and preferences for the citizen will have been persisted and will be synchronised across any other systems integrated with the platform. It is important that the entire Enriched Template object is mutated and sent to the submission endpoint as it contains additional metadata required to properly process the request. - [Get Consent State for a Citizen](https://docs-cpm.dataguard.com/reference/getconsentstate.md): The provided Template will be merged with the Citizen's current Permission and Preference state and be ready to render. A Template merged with Citizen state is known as an Enriched Template. If the Citizen does not exist, the request will succeed and all Permission and Preference values will default to false or null. - [Stateless Submission endpoint](https://docs-cpm.dataguard.com/reference/poststatelesssubmission.md) - [Get statement link histories.](https://docs-cpm.dataguard.com/reference/getstatementlinkshistory.md): Returns a list of statement link histories. This list will be in descending order based on the updatedAt field of the statement link - [Retrieve the configuration for the given application](https://docs-cpm.dataguard.com/reference/getpermissionsconfiguration.md) - [Updates a configuration for the given application](https://docs-cpm.dataguard.com/reference/updatepermissionsconfiguration.md) - [Creates transactions.](https://docs-cpm.dataguard.com/reference/createtransaction.md): Takes a list of EITHER one or more Change Transactions or a single Reversion Transaction to be processed. - [Retrieve transactions.](https://docs-cpm.dataguard.com/reference/gettransactions.md): The following criteria can be used to filter the results:

Note that if `citizenId` and `externalRef` are not provided, pagination will be enforced, with default values for `limit` and `offset` being used if none are provided. - [Retrieve the transaction for the given id.](https://docs-cpm.dataguard.com/reference/gettransaction.md) - [Redirect to latest revision of public PrivacyPolicy.](https://docs-cpm.dataguard.com/reference/redirectpublicprivacypolicyv2.md): This endpoint enables customers to embed a fixed URL in content such as websites or emails. Following URL will redirect to the Privacy Policy content. * for Privacy Policies that use Revisions, the latest content shall be used. * for Privacy Policies that do not use Revisions, the main content shall be used. * for Privacy Policies that do not have either, a 404 (Not found) status shall be returned. Privacy Policy Reference Limitations: * References must not contain forward slashes `/` since they are used to delimit the fields of the URL and may cause unpredictable behaviour. * While References may contain spaces, it not recommended since URLs should not (they are encoded as either `+` or `%20`). This may also cause unpredictable behaviour. * While certain characters may be encoded using `Percent Encoding`, for security reasons, this is not supported for all characters (e.g. forward slashes `/`, colons `:` etc.) - [Get Public Privacy Policies](https://docs-cpm.dataguard.com/reference/getpublicprivacypoliciesv2.md) - [Retrieves Job by ID.](https://docs-cpm.dataguard.com/reference/getcitizendeletionjobbyid.md) - [Creates a Citizen Deletion Job](https://docs-cpm.dataguard.com/reference/deletecitizens.md): Creates a job returning it's ID, which can be used to check on progress. Uploaded files shall be in CSV format that includes a header row. The format is shown in the Request body example below. Example table with required column to specify Citizen to delete.
externalRef
jb-mld-05
- [Retrieves a page of Jobs.](https://docs-cpm.dataguard.com/reference/getcitizendeletionjobs.md): This endpoint is paginated via the `limit` and `offset` parameters. - [Splits a citizen](https://docs-cpm.dataguard.com/reference/splitcitizens.md): Splits a citizen, resulting in the original citizen and a new or existing secondary citizen. Returns an enriched version of the request - [Retrieve a Citizen by its Id](https://docs-cpm.dataguard.com/reference/getcitizen.md) - [Retrieve a page of citizens for the given Application](https://docs-cpm.dataguard.com/reference/pagecitizensforapplication.md) - [Create citizens in bulk, up to 1000 at a time.](https://docs-cpm.dataguard.com/reference/createcitizens.md): Specify one or more citizens to be created along with their initial consent options. Returns the newly created citizens. - [Retrieve the number of citizens, associated with the given Application](https://docs-cpm.dataguard.com/reference/getcitizenssummary.md) - [Delete a single citizen by Citizen ID](https://docs-cpm.dataguard.com/reference/deletecitizen.md) - [Update a citizen](https://docs-cpm.dataguard.com/reference/updatecitizen.md): Specify the citizen's application details to be updated. Returns the updated citizen. - [Create a citizen](https://docs-cpm.dataguard.com/reference/createcitizen.md): Specify the `applicationId`, `externalRef`. Returns the newly created citizen. - [Query Citizens](https://docs-cpm.dataguard.com/reference/getcitizens.md): Search results are limited to 100 records. - [Delete a single citizen by Application ID and External Reference](https://docs-cpm.dataguard.com/reference/deletecitizenbyref.md) - [Lookup citizen email address](https://docs-cpm.dataguard.com/reference/getcitizenemailaddressbyexternalreference.md): Lookup citizen's email address from their externalRef - [Create or update citizen details](https://docs-cpm.dataguard.com/reference/upsertcitizenemailaddressdetails.md): Create or update citizen email address details - [Lookup citizen external ref](https://docs-cpm.dataguard.com/reference/getcitizenexternalreferencebyemailaddress.md): Lookup citizen's externalRef from their email address. NB: use request header in preference to request parameter as it supports `Plus Addressing`. - [Retrieves a page of linked citizen groups.](https://docs-cpm.dataguard.com/reference/getalllinkedcitizengroups.md): This endpoint is paginated by the limit and offset parameters. - [Link citizens to form a group](https://docs-cpm.dataguard.com/reference/createlinkedcitizens.md): Link citizens from different sources into a group. The group represents a citizen with data aggregated from all sources. Groups can contain from two to twenty members - [Get a group of linked citizens by reference.](https://docs-cpm.dataguard.com/reference/getlinkedcitizens.md): Get a group of linked citizens, where a member of the group matches the externalRef. - [Unlink a citizen from a group by reference](https://docs-cpm.dataguard.com/reference/deletelinkedcitizens.md): Unlink a citizen from a group where the citizen matches the externalRef. - [Merge a single citizen](https://docs-cpm.dataguard.com/reference/requestcitizenmerge-1.md): Please note that you cannot merge records that are already being merged, or have a previous transaction on a permission option that uses a lawful bases other than consent or legitimate interest (e.g. contract, legal obligation, public interest or vital interest). Attempting to merge such records will result in a failure being returned with an appropriate description. - [Retrieves all merges associated with the specified citizen or application](https://docs-cpm.dataguard.com/reference/getmergerequests-1.md): Behaviour of merges in progress is unspecified. Must provide either citizenId or applicationId, or an applicationId and externalRef - [Initiates a citizen merge job](https://docs-cpm.dataguard.com/reference/createmergejob-1.md): Takes a list of citizens to be merged - secondary into primary. Please note that you cannot merge records that are already being merged, or have a previous transaction on a permission option that uses a lawful bases other than consent or legitimate interest (e.g. contract, legal obligation, public interest or vital interest). Attempting to merge such records will result in a failure being returned with an appropriate description. - [Returns all citizen merge jobs for a specified Application Id](https://docs-cpm.dataguard.com/reference/getmergejobs-1.md): Returns citizen merge jobs for an application - [Returns information about a specific job](https://docs-cpm.dataguard.com/reference/getmergejob-1.md): Returns a citizen merge job - [Returns information about a specific job](https://docs-cpm.dataguard.com/reference/getmergejobresults-1.md): Returns a citizen merge job - [Retrieves a citizen merge](https://docs-cpm.dataguard.com/reference/getcitizenmerge-1.md): Retrieves a previous citizen merge - [Retrieves failure details for Job in CSV format.](https://docs-cpm.dataguard.com/reference/getcitizendeletionjobfailuresascsv.md): API error responses from this endpoint will be returned in JSON format. - [Imports Citizens, Transactions, Preferences and Email Addresses.](https://docs-cpm.dataguard.com/reference/importcapturedtransactions.md): Imports citizens with optional Transactions, Preferences and Email Addresses. Returns details about an import Job which can be used to check on the progress of the import. Upload files should be CSV files with the structure show in the example below, where the first row is column titles. Columns can appear in any order. Example table with required columns to create a citizen, transaction and preference. The following column headers can be added which specify additional optional fields on a transaction: `emailAddress, validFrom, validUntil, obtainedAt, source, campaign, channel, sourceSystem, sourceSystemReference`
uniqueReferenceprivacyPolicyIdpermissionStatementIdoptionIdoptionTypejustificationstatereferencevalues
uniqueRef-001prPol-01permStat-01opt-01groupconsentGRANTEDcontact-channels-preferencephone|post
- [Retrieves all Jobs.](https://docs-cpm.dataguard.com/reference/getimportjobs.md): This endpoint is paginated via the limit and offset parameters. - [Retrieves Job by ID.](https://docs-cpm.dataguard.com/reference/getimportjobbyid.md) - [Retrieve import job failures. NB: failure details are only available for 90 days.](https://docs-cpm.dataguard.com/reference/getimportjobfailures_1.md): This endpoint is paginated via the limit and offset parameters. - [Get captured citizen's details for the given ApplicationId.](https://docs-cpm.dataguard.com/reference/getcapturedcitizens.md): Retrieves previously stored citizens either in JSON format or exported to CSV depending on the Accept header provided. Please note: Retrieving citizens is a destructive action. Citizens that have been exported will not be included in additional requests unless the includeExported parameter is set to true. Example table with columns to demonstrate a Citizen represented as CSV:
uniqueReferenceapplicationIddata.firstNamedata.lastNamepartnercreatedAt
jb-mld-05d8BNrPqsgRZJoeBloggspartnerCompanyLtd2019-11-10T16:38:04Z
- [Capture a citizen's details.](https://docs-cpm.dataguard.com/reference/capturecitizen.md): Stores a single citizen data record. All records are deleted from the system thirty days from creation. Requires an API Key to be provided via a query parameter called 'key'. - [Retrieves all Jobs for Application](https://docs-cpm.dataguard.com/reference/getallpermissionsstoreexportjobs.md) - [Create a job to export permissions store data](https://docs-cpm.dataguard.com/reference/createpermissionsstoreexportjob.md) - [Retrieves Job by id](https://docs-cpm.dataguard.com/reference/getpermissionsstoreexportjob.md) - [Retrieve Linked Citizens import Job failures. NB: failure details are only available for 90 days.](https://docs-cpm.dataguard.com/reference/retrieveslinkedcitizenimportjobfailures.md): Retrieves failures encountered when processing a Job. This endpoint is paginated via the limit and offset parameters. - [Retrieve Linked Citizens import Job.](https://docs-cpm.dataguard.com/reference/retrieveslinkedcitizenimportjob.md) - [Import a CSV file of Linked Citizens.](https://docs-cpm.dataguard.com/reference/importslinkedcitizens.md): The CSV file requires a header row of ''reference,externalRef''.
Each subsequent row shall provide the Reference that groups citizen External References together.
References can group from one to twenty members, where groups of one will be unlinked from the group they currently belong to and groups of more than one will be linked together.
e.g.:
referenceexternalRef
group1citizen1
group1citizen2
group2citizen99
- [Update specific fields for a Subscription](https://docs-cpm.dataguard.com/reference/updatesubscriptionfieldsbyid.md): # Configuring a Subscription to meet your needs: There are a number of approaches that can be taken. ## Unauthenticated Webhook This is the simplest approach. Choose this if you want an unsecured Webhook. This is useful for development and testing purposes. NB: Bear in mind, if your endpoint is exposed to the public internet, then it may be open to abuse. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "authentication": { "authType": "none" } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __BODY__: `{ ... payload ... }` ## Webhook with API Key (Header) This approach is the best combination of simple and secure. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "authentication": { "authType": "api-key", "apiKeyAuth": { "location": "header", "value": "ABC1234", "key": "X-API-Key" }, } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _X-API-Key: ABC1234_ __BODY__: `{ ... payload ... }` ## Webhook with API Key (Query Parameter) Choose this approach if, for technical reasons, using HTTP headers is not possible. NB: Putting an API Key in a URL will mean that it likely logged and may be seen by unknown persons. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "authentication": { "authType": "api-key", "apiKeyAuth": { "location": "query", "value": "ABC1234", "key": "key" }, } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates?key=ABC123_ __BODY__: `{ ... payload ... }` ## Webhook with Bearer token Choose this approach if you or your organisation require Bearer tokens. NB: You will be required to manually replace expired tokens. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "authentication": { "authType": "token", "token": "ABC1234" } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _Authorization: Bearer ABC123_ __BODY__: `{ ... payload ... }` ## Webhook with OAuth2 Client Credentials Choose this approach if you or your organisation require Bearer tokens obtained from OAuth2 Client Credentials. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "authentication": { "authType": "oauth2", "oauth2Auth": { "grantType": "client-credentials", "authenticationUrl": "https://localhost:8080/oauth/token", "contentType": "application-form-urlencoded", "clientId": "", "clientSecret": "", "scope": "openid" } } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _Authorization: Bearer ABC123_ __BODY__: `{ ... payload ... }` ## Salesforce This provides integration with the Salesforce Connector. It requires a refresh token and a refresh url. The service will manage getting the first access token as well as renewing it upon expiry. ``` { "name": "my-subscription", "url": "https://hello.my.salesforce.com/services/apexrest/MyLifeDigital/EffectivePermissions", "status": "active", "authentication": { "authType": "token", "refreshToken": "{your refresh token}" "refreshUrl": "https://hello.my.salesforce.com/services/oauth2/token" } } ``` This will result in requests like this: __URL__: https://my-subscription/updates __HEADERS__: _Authorization: Bearer {access token}_ __BODY__: `{ ... payload ... }` - [Get a Subscription](https://docs-cpm.dataguard.com/reference/getsubscriptionbyid.md): Returns a Subscription identified by its Id. - [Delete a Subscription](https://docs-cpm.dataguard.com/reference/deletesubscriptionbyid.md) - [Update a Subscription](https://docs-cpm.dataguard.com/reference/updatesubscriptionbyid.md): # Configuring a Subscription to meet your needs: There are a number of approaches that can be taken. ## Unauthenticated Webhook This is the simplest approach. Choose this if you want an unsecured Webhook. This is useful for development and testing purposes. NB: Bear in mind, if your endpoint is exposed to the public internet, then it may be open to abuse. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "none" } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __BODY__: `{ ... payload ... }` ## Webhook with API Key (Header) This approach is the best combination of simple and secure. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "api-key", "apiKeyAuth": { "location": "header", "value": "ABC1234", "key": "X-API-Key" }, } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _X-API-Key: ABC1234_ __BODY__: `{ ... payload ... }` ## Webhook with API Key (Query Parameter) Choose this approach if, for technical reasons, using HTTP headers is not possible. NB: Putting an API Key in a URL will mean that it likely logged and may be seen by unknown persons. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "api-key", "apiKeyAuth": { "location": "query", "value": "ABC1234", "key": "key" }, } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates?key=ABC123_ __BODY__: `{ ... payload ... }` ## Webhook with Bearer token Choose this approach if you or your organisation require Bearer tokens. NB: You will be required to manually replace expired tokens. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "token", "token": "ABC1234" } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _Authorization: Bearer ABC123_ __BODY__: `{ ... payload ... }` ## Webhook with OAuth2 Client Credentials Choose this approach if you or your organisation require Bearer tokens obtained from OAuth2 Client Credentials. ``` { "name": "my-subscription", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "oauth2", "oauth2Auth": { "grantType": "client-credentials", "authenticationUrl": "https://localhost:8080/oauth/token", "contentType": "application-form-urlencoded", "clientId": "", "clientSecret": "", "scope": "openid" } } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _Authorization: Bearer ABC123_ __BODY__: `{ ... payload ... }` ## Salesforce This provides integration with the Salesforce Connector. It requires a refresh token and a refresh url. The service will manage getting the first access token as well as renewing it upon expiry. ``` { "name": "my-subscription", "url": "https://hello.my.salesforce.com/services/apexrest/MyLifeDigital/EffectivePermissions", "status": "active", "updateType": "effective-permission", "authentication": { "authType": "token", "refreshToken": "{your refresh token}" "refreshUrl": "https://hello.my.salesforce.com/services/oauth2/token" } } ``` This will result in requests like this: __URL__: https://my-subscription/updates __HEADERS__: _Authorization: Bearer {access token}_ __BODY__: `{ ... payload ... }` - [Get Subscriptions Configuration History](https://docs-cpm.dataguard.com/reference/getsubscriptionsaudits.md): Retrieves Subscriptions Configuration History ordered by timestamp, filtered by Application Id or Subscription Id if provided. - [Create a Subscription](https://docs-cpm.dataguard.com/reference/createsubscription.md): # Configuring a Subscription to meet your needs: There are a number of approaches that can be taken. ## Unauthenticated Webhook This is the simplest approach. Choose this if you want an unsecured Webhook. This is useful for development and testing purposes. NB: Bear in mind, if your endpoint is exposed to the public internet, then it may be open to abuse. ``` { "subscriptionType": "webhook", "name": "my-subscription", "applicationId": "d8BNrPqsgRZ", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "none" } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __BODY__: `{ ... payload ... }` ## Webhook with API Key (Header) This approach is the best combination of simple and secure. ``` { "subscriptionType": "webhook", "name": "my-subscription", "applicationId": "d8BNrPqsgRZ", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "api-key", "apiKeyAuth": { "location": "header", "value": "ABC1234", "key": "X-API-Key" }, } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _X-API-Key: ABC1234_ __BODY__: `{ ... payload ... }` ## Webhook with API Key (Query Parameter) Choose this approach if, for technical reasons, using HTTP headers is not possible. NB: Putting an API Key in a URL will mean that it likely logged and may be seen by unknown persons. ``` { "subscriptionType": "webhook", "name": "my-subscription", "applicationId": "d8BNrPqsgRZ", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "api-key", "apiKeyAuth": { "location": "query", "value": "ABC1234", "key": "key" }, } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates?key=ABC123_ __BODY__: `{ ... payload ... }` ## Webhook with Bearer token Choose this approach if you or your organisation require Bearer tokens. NB: You will be required to manually replace expired tokens. ``` { "subscriptionType": "webhook", "name": "my-subscription", "applicationId": "d8BNrPqsgRZ", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "token", "token": "ABC1234" } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _Authorization: Bearer ABC123_ __BODY__: `{ ... payload ... }` ## Webhook with OAuth2 Client Credentials Choose this approach if you or your organisation require Bearer tokens obtained from OAuth2 Client Credentials. ``` { "subscriptionType": "webhook", "name": "my-subscription", "applicationId": "d8BNrPqsgRZ", "url": "https://my-subscription/updates", "status": "active", "updateType": "consent-receipts", "authentication": { "authType": "oauth2", "oauth2Auth": { "grantType": "client-credentials", "authenticationUrl": "https://localhost:8080/oauth/token", "contentType": "application-form-urlencoded", "clientId": "", "clientSecret": "", "scope": "openid" } } } ``` This will result in requests like this: __URL__: _https://my-subscription/updates_ __HEADERS__: _Authorization: Bearer ABC123_ __BODY__: `{ ... payload ... }` ## Salesforce This provides integration with the Salesforce Connector. It requires a refresh token and a refresh url. The service will manage getting the first access token as well as renewing it upon expiry. ``` { "subscriptionType": "salesforce", "name": "my-subscription", "applicationId": "d8BNrPqsgRZ", "url": "https://hello.my.salesforce.com/services/apexrest/MyLifeDigital/EffectivePermissions", "status": "active", "updateType": "effective-permission", "authentication": { "authType": "token", "refreshToken": "{your refresh token}" "refreshUrl": "https://hello.my.salesforce.com/services/oauth2/token" } } ``` This will result in requests like this: __URL__: https://my-subscription/updates __HEADERS__: _Authorization: Bearer {access token}_ __BODY__: `{ ... payload ... }` - [Get all Subscriptions](https://docs-cpm.dataguard.com/reference/getsubscriptions.md): Returns a list of Subscriptions for the given Application Id. If no Application Id is provided, the endpoint returns Subscriptions for all applications you are authorised to access. - [Get all Webhook failures](https://docs-cpm.dataguard.com/reference/getsubscriptionsfailures.md): Retrieves a list of Webhook failures, filtered by Application Id, Subscription Id or date range if provided. - [Delete Webhook failures](https://docs-cpm.dataguard.com/reference/deletesubscriptionfailures.md): Delete Webhook failures, filtered by Application Id, Subscription Id, and optionally CitizenId OR a date range. - [Deletes Transactions by unique reference(s).](https://docs-cpm.dataguard.com/reference/deletetransactionsbyreference.md): Removes all existing transactions for a given set of references. This is a destructive action. Should be used to clear out unauthenticated Transactions for specific Citizens. - [Imports Transactions directly into the DataGuard Consent and Preference Management platform.](https://docs-cpm.dataguard.com/reference/importtransactions.md): Triggers a direct import of Transactions. The import will include all unauthenticated Transactions which have not previously been:
  • automatically imported via this endpoint
  • manually exported in CSV format via the GET endpoint
This will generate a Job that can be queried via the Captured Transactions Import API. The standard naming convention for Job reference is `Auto-Import-[ISO 8601 created timestamp].csv` The import will not include any deleted Transactions. - [Deletes Transactions.](https://docs-cpm.dataguard.com/reference/deletealltransactions.md): Removes all existing transactions. This is a destructive action and should only be used when the intention is to start fresh from a clean state. - [Creates an unauthenticated Transaction.](https://docs-cpm.dataguard.com/reference/createtransactions.md): Store transactions from unauthenticated user journeys. These can be manually exported to `CSV` and uploaded into the main Consent and Preference Management platform later. Calls to this endpoint do not require typical platform level authorisation but do need to have a valid `JSON` body and must pass field validation. - [Retrieves unauthenticated Transactions.](https://docs-cpm.dataguard.com/reference/retrieveunauthenticatedtransactions.md): Retrieves previously captured Transactions in either paginated `JSON` or `CSV` depending on the `Accept` header provided.

Please note:
Retrieving Transactions in CSV format is a destructive action. Transactions that have been exported in `CSV` format will not be included in additional requests unless the `includeExported` parameter is set to `true`. If the `includeExported` parameter is set to `true` and a `CSV` response is requested, only previously exported values will be included.
Additionally, Transactions that have previously been exported cannot be automatically imported into Consentric. Exporting the data in `CSV` format will not include any deleted Transactions.
Currently, the `JSON` response will retrieve all Transactions available, regardless of previous exports or deletions. Retrieving Transactions in JSON format will not mark them as exported.
Example table with columns to demonstrate a Transaction represented as `CSV`:
requestIduniqueReferenceapplicationIdpartnersourceSystemlocaletypeprivacyPolicyIdpermissionStatementIdoptionTypeoptionIdjustificationstateobtainedAtpreferenceIdreferencevaluesvalidFrom
6467264ca0918f5af8bb6706jb-mld-05d8BNrPqsgRZPartner Ltdsystem-456en-GBpermission1CxK7nWparQ25kEyrNschBoptionf8HbaconsentGRANTED1970-01-01T00:00:00.000ZS4x6IgHcontact-channelsphone|post1970-01-01T00:00:00.000Z
- [Define a preference](https://docs-cpm.dataguard.com/reference/createpreferenceconfiguration-2.md) - [Get all preferences](https://docs-cpm.dataguard.com/reference/getpreferencesconfigurations-2.md) - [Get a preference](https://docs-cpm.dataguard.com/reference/getpreferenceconfiguration-2.md) - [Update a preference](https://docs-cpm.dataguard.com/reference/updatepreferenceconfiguration-2.md) - [Delete a preference](https://docs-cpm.dataguard.com/reference/deletepreferenceconfiguration.md) - [Submit a citizen preference](https://docs-cpm.dataguard.com/reference/createpreference-2.md) - [Get preference submissions](https://docs-cpm.dataguard.com/reference/getpreferencessubmissions-2.md) - [Get a citizen submission](https://docs-cpm.dataguard.com/reference/getpreference-2.md) - [Get preferences for an application](https://docs-cpm.dataguard.com/reference/getpreferences-2.md) - [Get all history for preference configuration](https://docs-cpm.dataguard.com/reference/getpreferenceconfigurationshistory-2.md) - [Get history for a specific preference configuration](https://docs-cpm.dataguard.com/reference/getpreferenceconfigurationhistory-2.md) - [Deletes the tokens generated for the Job.](https://docs-cpm.dataguard.com/reference/deleteaccesstokenjobdata.md): This endpoint should be used to ensure that the tokens cannot be downloaded again. - [Creates a Job to generate Access Tokens.](https://docs-cpm.dataguard.com/reference/createaccesstokenjob.md): No more than 100,000 files may be stored for a single tenant. If no citizen IDs or external references are supplied in the request, tokens are created for all citizens. - [Retrieves the event logs.](https://docs-cpm.dataguard.com/reference/getaccesstokenjobevents.md) - [Revokes a Job and deletes the associated tokens](https://docs-cpm.dataguard.com/reference/deleteaccesstokenjob.md): This endpoint should be used to invalidate generated tokens within Consentric in case of security concerns. For example, if a previously downloaded list has been lost or compromised. - [Create a single access token for a specific citizen](https://docs-cpm.dataguard.com/reference/createaccesstokenforcitizen.md) - [Revoke a single Access Token](https://docs-cpm.dataguard.com/reference/revokeaccesstoken.md) - [Get the branding style.](https://docs-cpm.dataguard.com/reference/get_v1-branding.md) - [Update the branding. Note that if root objects like `styles` or `cardLayout` do not provided child attributes they are NOT overwritten.](https://docs-cpm.dataguard.com/reference/put_v1-branding.md) - [Get all branding history.](https://docs-cpm.dataguard.com/reference/get_v1-branding-history.md) - [Get template history](https://docs-cpm.dataguard.com/reference/gettemplateshistory.md): Returns a list of template events for a given applicationId - [Get full template history (not paginated)](https://docs-cpm.dataguard.com/reference/getfulltemplateshistory.md): Returns a list of template events for a given applicationId - [Retrieves Templates.](https://docs-cpm.dataguard.com/reference/retrievestemplatesforapplication.md) - [Creates a Template](https://docs-cpm.dataguard.com/reference/createtemplate.md) - [Retrieves Template by ID](https://docs-cpm.dataguard.com/reference/retrievestemplatebyid.md) - [Updates Template by ID](https://docs-cpm.dataguard.com/reference/updatetemplatebyid.md) - [Updates Template status](https://docs-cpm.dataguard.com/reference/updatetemplatestatus.md) - [Update a set of rules](https://docs-cpm.dataguard.com/reference/updatetemplaterules.md) - [Define a new set of rules](https://docs-cpm.dataguard.com/reference/createtemplaterules.md) - [Get all rules.](https://docs-cpm.dataguard.com/reference/getrulesforapp.md) - [Get a set of rules](https://docs-cpm.dataguard.com/reference/getrules.md) - [Delete a set of rules](https://docs-cpm.dataguard.com/reference/deleterules.md) - [Get all Widgets.](https://docs-cpm.dataguard.com/reference/getwidgets.md) - [Create a Widget](https://docs-cpm.dataguard.com/reference/createwidget.md) - [Get a Widget by ID](https://docs-cpm.dataguard.com/reference/getwidget.md) - [Update a Widget by ID](https://docs-cpm.dataguard.com/reference/updatewidget.md) - [Delete a Widget by ID](https://docs-cpm.dataguard.com/reference/deletewidget.md) - [Get all Widgets histories.](https://docs-cpm.dataguard.com/reference/getwidgetshistory.md) - [Get a Widget's history by ID](https://docs-cpm.dataguard.com/reference/getwidgethistory.md) - [Retrieves all Jobs.](https://docs-cpm.dataguard.com/reference/getaccesstokenjobsquery.md): As Job history grows over time intermittent 504 responses may occur. In this case please use multiple calls with offset and limit parameters provided. In this case Jobs are returned in order of most recently created first. - [Retrieves Job by ID.](https://docs-cpm.dataguard.com/reference/getaccesstokenjobbyid.md) - [Retrieves the tokens generated for a Job as CSV.](https://docs-cpm.dataguard.com/reference/getaccesstokenjobresults.md) ## Changelog - [Record marketing campaigns via capture points](https://docs-cpm.dataguard.com/changelog/record-marketing-campaigns-via-capture-points.md)