Overview

We provide partners with an easy to implement solution for sharing data in a private, secure way with your customers. Partners can use a Save It button on a web form, for example, to let individuals save a copy of the information they share on the form. Save It posts can also be triggered without the user interacting on the partner website; in this case, the partner post the data to Personal for the customer to claim. Save It gives the individual the ability to securely access a copy of that data for a variety of future benefits.

Save It is an alternative solution to utilizing our API for delivering data to Personal users. The benefit of Save It is that the recipient of the data does not need to be a registered Personal owner in order to receive data that is posted for them.

How Data Sharing Works

Data is sent using JSON posts to push data to a secure holding place on the Personal platform for a period of seven days. Once the post is pushed, an email is triggered to the customer, allowing them to register/login with Personal at a later time to claim that data. This minimizes the interruption to a user on the partner site.




Personal Guidelines

The following guidelines must be followed in order to assure security for both our partners and our users:

  • Personal will only interact with the DOM (Document Object Model) therefore we only support HTML. We do not support plug-in based technology such as Adobe Flash, Microsoft Silverlight or Java Applets
  • You may use any technology to create the HTTPS POST with the following requirements:
    • The POST must include the appropriate headers
    • The POST must include a crypto signature and a JSON payload from the server (i.e. the POST must be submitted from the server side and NOT the client side)
  • You must ensure that you have consent by the recipient to submit data to Personal on their behalf

Applying for a Personal API Key

Before you can begin posting data via Save It to Personal Owners, you will need to apply for a Personal API key (consumer key). This key will be sent with each Save It post you make, which will identify you as a trusted data source.

  1. To do so you will need to register for a Mashery account at:
    https://developer.personal.com/member/register
  2. Once you complete this registration you may then apply for the API key for Save It at:
    https://developer.personal.com/apps/register
    Note: Please make sure to indicate that you intend to use “Save It” it functionality and that you are applying for ‘Pipe’ key.
  3. When we receive and process your application, we will contact you with your Personal API key (consumer key) to use in the Save It post

User Data Routes

Posting user data utilizes a simple POST request. Data posted to Save It should be done so using the JSON (hash) format for the POST body.


Test route for POST:

https://api-sandbox.personal.com/api/v1/pipes?client_id=<consumer_key>&sig=<mashery_signature>


Production route for POST:

https://api.personal.com/api/v1/pipes?client_id=<consumer_key>&sig=<mashery_signature>


Key and Mashery Signature

<key>

This is the API key that you received when you registered with Mashery. This key will identify you as someone who has the necessary rights to POST to Personal using Save It. Please make sure you use the "Pipe" key that we sent to you.


<mashery_signature>

This is used and validated by Mashery as a security measure. To generate your Mashery signature, follow these steps:

  1. Concatenate these three values: key, shared secret for given key (this can be found once you login into your Mashery account) and current unix timestamp (GM time)
  2. Hash the concatenated value using SHA256 hash algorithm.
  3. The resulting value should be used as the mashery_signature

Response codes

After submitting data to the predefined route, you should receive one of the following responses:

  • 200 => Successful
  • 400 => Bad request
  • 403 => Permission denied: In this case it does not appear that you have the rights to post to Personal. Contact us and we can help you troubleshoot the problem – it is most likely an issue with your keys in the post.
  • 404 => The route does not exist: See “Save It Routes” to confirm that your URLs are correct.
  • 500 => Personal internal error

Overview

The JSON post will include information to specify which Personal fields your data should be mapped to. With this option, you may also define the gem name that will appear in the user’s vault, as well as any specific metadata to accompany the gem.

Content-type Header

Content-type header must be set to 'application/json'.

Data Format

        {
            "to" : "<user's email address>",
            "type" : "signup",
            "account" : {
                "code": "<unique partner code - contact us to obtain your code>"
            },
            "data" : {
                "new0.<p3name>": "<data>",
                "new0.<p3name>": "<data>",
                "new1.<p3name>": "<data>",
                "new1.<p3name>": "<data>",
                .
                .
                .
                "newn.<p3name>": "<data>",
                "newn.<p3name>": "<data>",
                "newn.<p3name>": "<data>"
            },
            "context" : {
                new0 : {
                    "name_template": "${new0.p3name}'s <context0 static text>",
                    "metadata" : {
                        "tag" : "['<tag_name0>', '<tag_name1>']"
                    }
                },
                new1 : {
                    "name" : "<context1 static text>",
                    "metadata" : {
                        "tag" : "['<tag_name0>', '<tag_name1>']"
                    }
                },
                .
                .
                .
                newn : {
                    "name" : "<contextn static text>",
                    "metadata" : {
                        "tag" : "['<tag_name0>', '<tag_name1>']"
                    }
                },
               "custom": "false"
            }

          

User identification

This is required information and must contain a valid email address for the receiving user. The user may or may not be a registered Personal user.

Data type

In this section you may describe what type of data is being sent. Based on this 'type', we can customize the welcome email that is sent to your users. The default value should be 'signup', which will give the default email message. If a custom email has been created for you, we may give you an alternative value to place here.

Account Code

In this section, you define the partner code to apply to all newly created accounts. If a code is not specified, we will apply your default partner code, if one exists. If there is no default code associated with your API key, the default Personal trial code will be applied. Please contact support@personal.com to obtain your partner code.

Custom

This flag is used to specify whether the POST body is using the Custom or Non-Custom format. For your posts we will be utilizing the non-custom post format therefore the flag should be set to “false”.

Date format: Newn.p3name

    newn

    This is optional if you are only sending one version of each type of data - i.e., one firstName, one lastName, one address, etc.

    This defines which Context definition to reference for this data (see the Context Definition section of the post). If used, this value will have a corresponding Context section defined.

    If your Save It post is sending multiple versions of the same Personal data field, each version should have a different <newn> prefix for the field in the JSON post. The context prefix defines the name of the context section. The context definition must have a prefix of 'new', followed by a context number, i.e, new0, new1, new2, etc.


    p3name

    This MUST BE included. This describes the field in the Personal schema that this data should be mapped into.

    View the Data Ontology to see all data fields Personal supports.

    If you provide your form or sample data to Personal, we will define the Personal Field for each data field. If you have data that does not match Personal's data ontology, please contact us and we will investigate adding it to our ontology.

Context Definition

The entire “Context” section is optional, but will enhance the experience of your users. We recommend completing this section as part of your Save It post.

    Context Naming with <name> or <name-template>

    This will define the name of the gem(s) where data tagged with this context definition will be stored. If data is not specified for <instance_name> our system will assign a name based on the data passed.

    Use the <name> parameter if you would like to name the data with static content - such as 'Home Phone' or 'Work Address'. Use the <name_template> parameter if you would like the data to drive the name - such as 'Mary's Email' or 'John's Insurance'.

      "name": "Work Address" 

    or


      "name_template": "${new0.preferred_first_name}'s Email"

    In the <name_template> example, the ${new0.preferred_first_name} means that the data defined in the new0 context as preferred_first_name would populate the gem name with the static context of "'s Email" to make the gem name something like "Mary's Email".


    Only one of the <name> or <name_template> parameters should be defined in each context section. If only static text is used, the <name> parameter will yield better performance.


    Note: You will most likely create multiple gems with your Save It post. Personal can help you make sure you are defining the context correctly so the gems are logically named in the recipient’s vault.


    <tag>

    This is optional information. Tags are used in Personal for organizational purposes. Each gem may be assigned multiple tags and tags may be repeated across gems to show a correlation between them. Tags are searchable in Personal as well. This is used to define one or more tags to be assigned to the gem for the field assigned the corresponding context section. Each tag should be separated by a "," .

JSON POST Example

The following is an example of a valid basic JSON Save It post.

        {
            "to" : “homer@personal.com”,
            "type" : "signup",

            "data" : {
            "to": "homer@personal.com",
            "type": "signup",
            "data": {
              "new0.firstName": "Homer",
              "new0.lastName": "Simpson",
              "new1.firstName": "Marge",
              "new1.lastName": "Simpson",
              "new2.streetAddress1": "742 Evergreen Terrace",
              "new2.city": "Springfield",
              "new2.state": "VA",
              "new2.postalCode": "22009",
              "new3.streetAddress1": "3 Iverson Street",
              "new3.streetAddress2": "Suite 100",
              "new3.city": "Philadelphia",
              "new3.state": "PA",
              "new3.postalCode": "19102"
           },
           "context": {
              "new0": {
              "name_template": "${new0.firstName}",
              "metadata": {
                 "tag": ["Homer"]
              }
           },
              "new1": {
              "name_template": "${new1.firstName}",
              "metadata": {
                 "tag": ["Marge"]
              }
           },
              "new2": {
              "name": "HomeAddress",
              "metadata": {
                 "tag": ["Homer","Marge"]
              }
           },
              "new3": {
              "name": "WorkAddress",
              "metadata": {
                 "form_template": ["Homer"]
              }
         }
       },
       "custom": "false"
   }

        

Overview

For an additional level of security we have include a feature called user authentication. This allows you to require that users answer a series of questions to verify their identity. When you POST data using Save It you may require that the recipient verify either a token or a set of data fields before the data may be imported to their Vault. If the user fails to answer the questions correctly, the data you have sent will be safely discarded. If the user is a first time user the registration process will be completed however their Vault will be empty. The token or specific data fields will be specified in the body of the JSON POST as described in this section.

Auth

When user authentication is to be used an auth section should be included below the data section of the POST body.

    token

    If you choose to send a custom token for a user to verify you may specify the value with this variable in the following format:
    "token": <custom token value>

    fields

    You may also choose to use one or more of the data fields passed in the data section of the post as fields for user authentication. This is specified using the "fields" variable in the following format:
    "fields" : ["<field_name_1>", "<field_name_2>", ... "<field_name_n>"]

    fields_questions

    When you are using fields for user authentication you may also specify the question that will be displayed for each field on the authentication form. If you do not specify a question for each field the field name will be displayed. This is specified using the "fields_questions" variable in the following format:
    "fields_questions" : {"<field_name_1>" : "Question text", "<field_name_2>" : "Question text", ... "<field_name_n>" : "Question text",}

    attempts

    You may specify how many attempts a user may make when answering the authentication questions before they are unable to complete the data import. The default number of attempts is = 3. You may set this to a number from 1 to n. The user will be notified when they have reached their last attempt. If they exceed their number of attempts the data you have sent for this user will be safely discarded and they will be directed to contact you for assistance. If they were a new user, their registration will complete and they will have access to their empty Vault.
    This is specified using the "attempts" variable in the following format:
    "attempts" : <n>

    enforce

    You may speficy when the user authentication is enforced. There are two options:

    1. always = the user will be required to answer the authentication questions every time they attempt to claim data sent by you. This is the default setting if not specified in the POST.

    2. once = the user will only be required to answer the authentication questions if it is their initial first time claiming data from you.

    This is spefied using the "enforce" variable in the following format:
    "enforce" : "<once|always>"

Field Authentication Example

Here is an example using field authentication, adding on to the previous JSON POST Example

        {
            .
            .
            .
            "auth":{
              "fields":[
                "new0.firstName",
                "new0.lastName",
                "new2.postalCode"
              ],
              "fields_questions":{
                "new0.firstName": "What is your first name?",
                "new0.lastName": "What is your last name?",
                "new2.postalCode": "What is your zip code?"
              },
              "attempts": 2,
              "enforce": "once"
            }
        }
        

Token Authentication Example

Here is an example using token authentication, adding on to the previous JSON POST Example

      {
          .
          .
          .
          "auth":{
            "token": "abc1234",
            "attempts": 2,
            "enforce": "once"
          }
      }
      

User Experience

When a user has clicked to claim their data from the notification email, they will be taken to the Personal registration/login screen as with the non-authentication flow. Once they complete login/registration they will be presented with a screen asking them to validate the data you have indicated as the user authentication data in your POST request.


First Attempt

The data fields along with the questions specified in the POST (field name if questions are not specified) are displayed. If the user answers all questions correctly the data will be imported and they will be taken to their Vault.




Invalid Answer (last attempt)

When a user answers one or more questions incorrectly the system will highlight which fields require correction. If this is their last attempt they will be notified as such.




All Attempts Failed

In the case where the user fails each of their allowed attempts they will be presented with a message informing them that the data will not be imported to their Vault.


Overview

Once data has been submitted to Personal via Save It, the specified recipient will receive an email notifying them that they have data waiting for them.

Below are examples of the notification email. There are two versions of this email: one for existing Personal users, and one for users that have not previously registered. Images, colors and text may be customized to meet your needs. The Personal product manager will work with you to determine if any changes are to be made.

Existing User



New User