Getting Started with FullContact Permission API

When creating Permissions for a consumer record you need to be sure to define permission purposes and relevant channels for your business. We have built out a data purposes taxonomy or all your needs but should you wish to adhere to IAB purposes we have those built into our permissions service as well.

Download our purposes data model with the ability to store consents across web, mobile, email, phone and offline channels.

Create Permission

Create a new permission for a given consumer record. A successful creation request will result in a 202 Response.

The following fields are required to create a permission:

One or many of the acceptable multi field inputs
Permission Purposes purpose ID, enabled (true/false) & channel (unspecified or a valid channel of email, mobile, web, phone and/or offline)
Collection Method
Collection Location
Policy URL
Terms of Service

curl -X POST \
  https://api.fullcontact.com/v3/permission.create \
  -H "Content-Type: application/json" \
  -d '{
	"timestamp": 21092109,
	"query": {
		"emails": [
			"[email protected]",
			"[email protected]"
		],
		"phones": [
			"+17202227799",
			"+13035551234"
		],
		"location": {
			"addressLine1": "123 Main Street",
			"addressLine2": "Unit 2",
			"city": "Denver",
			"region": "Colorado",
			"regionCode": "CO",
			"postalCode": "80203"
		},
		"name": {
			"full": "Bart Lorang",
			"given": "Bart",
			"family": "Lorang"
		},
		"profiles": [{
			"service": "twitter",
			"username": "bartlorang"
		}, {
			"service": "twitter",
			"userid": "5998422"
		}, {
			"service": "linkedin",
			"url": "https://www.linkedin.com/in/bartlorang"
		}, {
			"service": "github",
			"url": "https://www.github.com/lorangb"
		}],
	"maids": ["adkkjre", "alkdjfakd"]
	},
	"consentPurposes": [{
			"purposeId": 2,
			"channel": ["web", "phone"],
			"ttl": 365,
			"enabled": true
		},
		{
			"purposeId": 3,
			"channel": ["mobile"],
			"ttl": "NULL",
			"enabled": true
		}
	],
	"locale": "US",
	"ipAddress": "127.0.0.1",
	"language": "en",
	"collectionMethod": "cookiePopUp",
	"collectionLocation": "https://kenblahblah.com",
	"tcf": "some.valid.tcfv2.string",
	"policyUrl": "http://foo.baz",
	"termsService": "http://foo.tos"
}

Delete Permission

Delete a previously permitted consumer record by providing one or many of the acceptable multi field inputs. A successful deletion request will result in a 200 Response.

curl -X POST \
  https://api.fullcontact.com/v3/permission.delete \
  -H "Content-Type: application/json" \
  -d '{
	  "emails": [
	    "[email protected]",
	    "[email protected]"
	  ],
	  "phones": [
	    "+17202227799",
	    "+13035551234"
	  ],
	  "location": {
	    "addressLine1": "123 Main Street",
	    "addressLine2": "Unit 2",
	    "city": "Denver",
	    "region": "Colorado",
	    "regionCode": "CO",
	    "postalCode": "80203"
	  },
	  "name": {
	    "full": "Bart Lorang",
	    "given": "Bart",
	    "family": "Lorang"
	  },
	  "profiles": [{
	    "service": "twitter",
	    "username": "bartlorang"
	    }, {
	    "service": "twitter",
	    "userid": "5998422"
	    }, {
	    "service": "linkedin",
	    "url": "https://www.linkedin.com/in/bartlorang"
	    }, {
	    "service": "github",
	    "url": "https://www.github.com/lorangb"
	    }],
	  "maids" : [ "adkkjre" , "alkdjfakd" ]
}

Find Permission

Find and retrieve the permission history for an individual using one or many of the acceptable multi field inputs. A successful response will return all permissions history for an individual.

curl -X POST \
  https://api.fullcontact.com/v3/permission.find \
  -H "Content-Type: application/json" \
  -d '{
	  "emails": [
	    "[email protected]",
	    "[email protected]"
	  ],
	  "phones": [
	    "+17202227799",
	    "+13035551234"
	  ],
	  "location": {
	    "addressLine1": "123 Main Street",
	    "addressLine2": "Unit 2",
	    "city": "Denver",
	    "region": "Colorado",
	    "regionCode": "CO",
	    "postalCode": "80203"
	  },
	  "name": {
	    "full": "Bart Lorang",
	    "given": "Bart",
	    "family": "Lorang"
	  },
	  "profiles": [{
	    "service": "twitter",
	    "username": "bartlorang"
	    }, {
	    "service": "twitter",
	    "userid": "5998422"
	    }, {
	    "service": "linkedin",
	    "url": "https://www.linkedin.com/in/bartlorang"
	    }, {
	    "service": "github",
	    "url": "https://www.github.com/lorangb"
	    }],
	  "maids" : [ "adkkjre" , "alkdjfakd" ]
}

[
    {
        "permissionType": "create",
        "permissionId": "6743a05d-3f5c-40d7-be82-6b3500c6eb05",
        "consentPurposes": [
            {
                "purposeId": 5,
                "channel": "phone",
                "ttl": null,
                "enabled": true,
                "timestamp": 1580316049169
            },
            {
                "purposeId": 5,
                "channel": "web",
                "ttl": null,
                "enabled": true,
                "timestamp": 1580316049169
            },
            {
                "purposeId": 5,
                "channel": "mobile",
                "ttl": null,
                "enabled": true,
                "timestamp": 1580316049169
            },
            {
                "purposeId": 2,
                "channel": "web",
                "ttl": null,
                "enabled": true,
                "timestamp": 1580316049169
            }
        ],
        "locale": "JA",
        "ipAddress": "8.8.8.8",
        "language": "japanese",
        "collectionMethod": "verbal",
        "collectionLocation": "https://kenblahblah.com",
        "policyUrl": "https://cnn.com//asdfpolicy",
        "termsService": "https://cnn.comasdf/terms",
        "timestamp": null,
        "created": 1580316049212
    },
    {
        "permissionType": "create",
        "permissionId": "7ede6fa3-743a-4dcb-a296-53dd9b76d346",
        "consentPurposes": [
            {
                "purposeId": 5,
                "channel": "phone",
                "ttl": null,
                "enabled": true,
                "asOfTimestamp": 1580316115089
            },
            {
                "purposeId": 5,
                "channel": "web",
                "ttl": null,
                "enabled": true,
                "asOfTimestamp": 1580316115089
            },
            {
                "purposeId": 5,
                "channel": "mobile",
                "ttl": null,
                "enabled": true,
                "asOfTimestamp": 1580316115089
            }
        ],
        "locale": "EU",
        "ipAddress": "1.2.3.4",
        "language": "EN",
        "collectionMethod": "verbal",
        "collectionLocation": "https://kenblahblah.com",
        "policyUrl": "https://cnn.com//asdfpolicy",
        "termsService": "https://cnn.comasdf/terms",
        "tcf": ["some.valid.tcfv2.string"],
        "timestamp": null,
        "created": 1580316115153
    }
]

Retrieve Current Permission

Retrieve an individual's current permissions state by purpose by providing one or many of the acceptable multi field inputs. Response will return the current permissions state by purpose for an individual.

Example Permission Current Request

curl -X POST \
  https://api.fullcontact.com/v3/permission.current \
  -H "Content-Type: application/json" \
  -d '{
	  "emails": [
	    "[email protected]",
	    "[email protected]"
	  ],
	  "phones": [
	    "+17202227799",
	    "+13035551234"
	  ],
	  "location": {
	    "addressLine1": "123 Main Street",
	    "addressLine2": "Unit 2",
	    "city": "Denver",
	    "region": "Colorado",
	    "regionCode": "CO",
	    "postalCode": "80203"
	  },
	  "name": {
	    "full": "Bart Lorang",
	    "given": "Bart",
	    "family": "Lorang"
	  },
	  "profiles": [{
	    "service": "twitter",
	    "username": "bartlorang"
	    }, {
	    "service": "twitter",
	    "userid": "5998422"
	    }, {
	    "service": "linkedin",
	    "url": "https://www.linkedin.com/in/bartlorang"
	    }, {
	    "service": "github",
	    "url": "https://www.github.com/lorangb"
	    }],
	  "maids" : [ "adkkjre" , "alkdjfakd" ]
}

{
    "1": {
        "phone": {
            "purposeId": 1,
            "channel": "phone",
            "ttl": null,
            "enabled": false,
            "timestamp": 1580256602657
        },
        "web": {
            "purposeId": 1,
            "channel": "web",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580256796937
        }
    },
    "2": {
        "mobile": {
            "purposeId": 2,
            "channel": "mobile",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580310750037
        },
        "web": {
            "purposeId": 2,
            "channel": "web",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580310750037
        },
        "phone": {
            "purposeId": 2,
            "channel": "phone",
            "ttl": null,
            "enabled": false,
            "timestamp": 1580256627980
        },
        "offline": {
            "purposeId": 2,
            "channel": "offline",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580310750037
        },
        "cable": {
            "purposeId": 2,
            "channel": "cable",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580256616977
        }
    },
    "3": {
        "phone": {
            "purposeId": 3,
            "channel": "phone",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580311488332
        }
    },
    "5": {
        "phone": {
            "purposeId": 5,
            "channel": "phone",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580308507055
        },
        "web": {
            "purposeId": 5,
            "channel": "web",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580308507055
        },
        "mobile": {
            "purposeId": 5,
            "channel": "mobile",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580308507055
        },
        "email": {
            "purposeId": 5,
            "channel": "email",
            "ttl": null,
            "enabled": true,
            "timestamp": 1580308507055
        }
    }
}

Verify Permission

Retrieve and verify the permission state for an individual by purpose and channel. Response will return the current purposes and whether or not an individual has provided permissions.

The following fields are required to verify a permission:

One or many of the acceptable multi field inputs
Permission Purposes purpose ID & channel (unspecified or a valid channel of email, mobile, web, phone and/or offline)

curl -X POST \
  https://api.fullcontact.com/v3/permission.verify \
  -H "Content-Type: application/json" \
  -d '{
  "query": {
	  "emails": [
	    "[email protected]",
	    "[email protected]"
	  ],
	  "phones": [
	    "+17202227799",
	    "+13035551234"
	  ],
	  "location": {
	    "addressLine1": "123 Main Street",
	    "addressLine2": "Unit 2",
	    "city": "Denver",
	    "region": "Colorado",
	    "regionCode": "CO",
	    "postalCode": "80203"
	  },
	  "name": {
	    "full": "Bart Lorang",
	    "given": "Bart",
	    "family": "Lorang"
	  },
	  "profiles": [{
	    "service": "twitter",
	    "username": "bartlorang"
	    }, {
	    "service": "twitter",
	    "userid": "5998422"
	    }, {
	    "service": "linkedin",
	    "url": "https://www.linkedin.com/in/bartlorang"
	    }, {
	    "service": "github",
	    "url": "https://www.github.com/lorangb"
	    }],
	  "maids" : [ "adkkjre" , "alkdjfakd" ]
	  },
  "purposeId" : 2,
  "channel" : "web"
}

{
   "ttl": null,
   "enabled": true,
   "channel": "web",
   "purposeId": 8,
   "purposeName": "Precise Geographic Location Data (Linkage & Identity)",
   "timestamp": 1580316049169
}

Permission in Enrich

For those customers who are already using FullContact's Enrich Product you now have the capability to capture and continuously manage the permissions and preferences of your consumer as well as receive insights back via our Enrichment Insights Bundles. Create opted-in consumer permissions by passing over the consent string within the body the JSON request.

The following fields are required to create a permission:

One or many of the acceptable multi field inputs
Permission Purposes purpose ID, enabled (true/false) & channel (unspecified or a valid channel of email, mobile, web, phone and/or offline)
Collection Method
Collection Location
Policy URL
Terms of Service

curl -X POST \
  https://api.fullcontact.com/v3/person.enrich \
  -H "Content-Type: application/json" \
  -d '{
	"email": "[email protected]",
	"maids": ["adkkjre", "alkdjfakd"],
	"permission": {
		"consentPurposes": [{
				"purposeId": 2,
				"channel": ["web", "phone"],
				"ttl": 365,
				"enabled": true
			},
			{
				"purposeId": 3,
				"channel": ["mobile"],
				"ttl": "NULL",
				"enabled": true
			}
		],
	"locale": "US",
	"ipAddress": "127.0.0.1",
	"language": "en",
	"collectionMethod": "cookiePopUp",
	"collectionLocation": "https://kenblahblah.com",
	"policyUrl": "http://foo.baz",
	"termsService": "http://foo.tos"
	}
}