Iubenda logo
Start generating

Documentation

Table of Contents

API docs: How to Use the API

Lets assume that we’d like to create a privacy policy for a user with the following characteristics:

  • Website: www.userwebsite.com
  • Email: user.name@gmail.com
  • Website owner: User Name, Via Roma, 18 – 20123 Milano (MI) – Italy
  • The key to get access to our API (API Key):  c4f88fe3247f7df3f232025438596d54b59b76f8

All that you need to do is to call the iubenda API, providing the above paramenters, which will return:

  • The link to the generated privacy policy
  • The code to embed the privacy policy into a website
  • A special link that does not require a login, to modify the privacy policy
  • An ID to recall the information in the future

Example

The API is provided in JSON. Below you will find an example:

Privacy Policy Creation

POST

https://www.iubenda.com/api/transactions

POST Data

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email" => "user.name@gmail.com",
  },
  "privacy_policy" => {
    "url" => "www.userwebsite.com",
    "owner" => {
      "info" => "User Name, Via Roma, 18 - 20123 Milano (MI) - Italy",
      "email" => "owner.mail@iubenda.com"
      },
    "cookie_solution" => true
    
  }
}

ANSWER CALL

"transaction_id" => 597127324 // transaction ID
"output" => {
  "user" => {
    "id" => 20952, // ID of the user we created
    "email" => "user.name@gmail.com" // The user's email, previously provided 
  }
  "privacy_policies" => [
    {
      "id" => 19276,
      "site_id" => 193712,
      "public_id" => 193847,
      "lang" => "en",
      "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/services?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/edit?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "embed_code" => "Privacy Policy"
    }
  ]
}
"errors" =>
"success" => true
"api_version" => "1.0"

In the answer call, the usable data is:

  • transaction_id: The transaction ID helps to recall the data of the generated privacy policy at any time
  • output => privacy_policies => edit_url: the modification link that allows the user to manage and modify his privacy policy
  • output => privacy_policies => policy_url: the link to the generated privacy policy
  • output => privacy_policies => embed_code: the embedding code that the user needs to paste into his own website. This code shows a link that opens the privacy policy in a modal window. The user may choose to integrate the privacy policy directly adding the link from the previous “policy_url”

It’s important to note that the transaction_id needs to be saved to a database in order to access the data related to the privacy policy later on.

Set the privacy policy languages

It is possible to specify a list of languages in which we want the privacy policy to be generated.

The languages list must be provided as an array of language codes for the parameter args.privacy_policy.langs, as shown in the example below. Allowed language codes are: “nl”, “en-GB”, “en”, “fr”, “de”, “it”, “pt-BR”, “ru” and “es”. If no language code is provided, US English (“en”) is assumed (see the example above).

The generated privacy policies (one per provided language) will be returned in the output.privacy_policies property of the JSON response (see example below).

POST Data

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email" => "user.name@gmail.com",
  },
  "privacy_policy" => {
    "url" => "www.userwebsite.com",
    "langs" => ["it", "en"],
    "owner" => {
      "info" => "User Name, Via Roma, 18 - 20123 Milano (MI) - Italy",
      "email" => "owner.mail@iubenda.com"
      },
    "cookie_solution" => true 
    
  }
}

ANSWER CALL

"transaction_id" => 597198825 // transaction ID
"output" => {
  "user" => {
    "id" => 20952, // ID of the user we created
    "email" => "user.name@gmail.com" // The user's email, previously provided 
  }
  "privacy_policies" => [
    {
      "id" => 964529,
      "site_id" => 927554,
      "public_id" => 8239444,
      "lang" => "it",
      "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/964529/services?l_email=user.name@gmail.com&l_tok=C1oy1Dt0xiRL3I0LHC",
      "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/964529/edit?l_email=user.name@gmail.com&l_tok=C1oy1Dt0xiRL3I0LHC",
      "embed_code" => "Privacy Policy"
    },
    {
      "id" => 964530,
      "site_id" => 927554,
      "public_id" => 8239445,
      "lang" => "en",
      "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/964530/services?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/964530/edit?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
      "embed_code" => "Privacy Policy"
    },
  ]
}
"errors" =>
"success" => true
"api_version" => "1.0"

Advanced parameters

Following is the list of all the accepted parameters

"api_key" => "c4f88fe3247f7df3f232025438596d54b59b76f8",
"type" => "create_privacy_policy",
"args" => {
  "user" => {
    "email"  => "user.name@gmail.com",
    "pwd"    => "password",  // required in case in case user is already created/registered
    "lang"   => "it",        // optional, in case of creating user, available 'en' and 'it', default to 'en'
    "c_code" => "DE",        // optional, in case of creating user, the 2-digit ISO Alpha-2 country info of 
                                //           the user; if not provided, no country info will be set for the user
  },
  "privacy_policy" => {
    "type" => "web_site",             // optional, available 'web_site' and 'mobile_app', default to 'web_site'
    "url"  => "www.userwebsite.com",  // required in case 'type' is not provided or is 'web_site'
    "app_name" => "testApp",          // required in case 'type' is 'mobile_app'
    "langs" => ['it', 'en'],          // optional, default to ['en'] (see above for more info in setting languages)
    "owner" => {                      // optional
      "info"  => "User Name, Via Roma, 18 - 20123 Milano (MI) - Italy",
      "email" => "owner.mail@iubenda.com"
    },
    "pro" => true,  // optional, default to 'false'; if provided 'true' the privacy policy will be created with
                      //           Pro feature and a 1 Year Pro license will be associated to the privacy policy
                      // NOTE: the api account must be allowed to create Pro policies, otherwise an error will be
                      //       returned
                      // NOTE: in case the destination user has got an active multi licenses plan, the privacy
                      //       policy will be created Pro no 
matter of this parameter
    "cookie_solution" => true,  // optional, default 'false';
                      // if provided 'true', a cookie solution will be created  
                      // with a 25k pageviews/month free plan, if the user hasn't one yet.

    "skip_configuration_mail" => true,  // optional, default 'false'; if provided 'true' no configuration mail for
                                          //           the just created Privacy Policy will be sent to the destination 
                                          //           user email address
  }
}

Recall a privacy policy after generation

To recall a previously generated privacy policy do a GET call towards our API, using the API Key and the transaction_id that was received upon creation.

GET

https://www.iubenda.com/api/transactions/transaction_id?api_key=api_key_value

Example:

https://www.iubenda.com/api/transactions/597127324?api_key=c4f88fe3247f7df3f232025438596d54b59b76f8

ANSWER CALL

=> {
  "id" => 193847,
  "transaction" => {
    "success" => true,
    "type" => "create_privacy_policy",
    "input" => {
      "user" => {
        "email" => "user.name@gmail.com",
        "lang" => "en",
        "c_code" => "EN"
      },
      "privacy_policy" => {
        "url" => "www.userwebsite.com",
        "langs" => ["en"],
        "owner" => {
          "info" => "User Name, Via Roma, 18 - 20123 Milano (MI) - Italy",
          "email" => "user.name@gmail.com"
        }
      }
    },
    "output" => {
      "user" => {
        "id" => 6269,
        "email" => "user.name@gmail.com"
      },
      "privacy_policies" => [
        {
          "id" => 19276,
          "site_id" => 193712,
          "public_id" => 193847,
          "lang" => "en",
          "setup_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/services?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
          "edit_url" => "https://www.iubenda.com/it/privacy-policy-generator/19276/edit?l_email=user.name@gmail.com&l_tok=enL39d1xhk1RPPRuW8U5",
          "policy_url" => "https://www.iubenda.com/privacy-policy/193847",
          "embed_code" => "Privacy Policy"
        }
      ]
    }
  },
  "errors" => [],
  "success" => true,
  "api_version" => "1.0",
  "test" => false
}

From this answer call you can extract all the values at output => privacy_policies.  Please note that privacy_policies is an array that in this scenario is always composed of a single element.