check_submission_is_unique.html

---
layout: default
navPage: docs
heading: checkSubmissionIsUnique()
breadcrumbs:
  - API,/api/
  - API v2.x,/api/v2
  - Class Methods,/api/v2/class_methods/
  - Other Functions,/api/v2/other_functions/
  - checkSubmissionIsUnique()
prev: deleteUnfinalizedSubmissions(),/api/v2/delete_unfinalized_submissions/
next: displayPostFormCaptchaError(),/api/v2/display_post_form_captcha_error/
versions: FT3
categories: api
tags: developer,submissions
---

{% include open_section.html nav='nav_api_v2.html' selected='check_submission_is_unique' nav_width=4 %}

	<p>
		This function lets you check that
		a submission is unique, based on whatever criteria is required for your form. For example,
		a common usage of this function is to check that a submission currently being placed has
		NOT already been placed by someone with the same email address.
	</p>

	<p>
		The function can be called like so:
	</p>

	{% codemirror php %}
$api = new FormTools\API();
if ($api->checkSubmissionIsUnique($form_id, $criteria, $submission_id)) {
    echo "oh it's unique all right!";
}
	{% endcodemirror %}

	<p>
		The <b>$form_id</b> parameter is self-explanatory; you can find this value in your Form Tools interface.
        <b>$criteria</b> is a hash/associative array where the keys are the database column names and the values are
        the values being examined. This field can contain any number keys. The third <b>$submission_id</b> parameter
        is OPTIONAL, and was added in version 20090905 of the API. This lets you tell the function to ignore a particular
		submission when doing to the comparison. In other words, it ensures that it doesn't run the test for uniqueness
        against itself - because that would always fail!
	</p>

	<p>
		To return to our example, imagine you want to check that a submission hasn't already been placed by a user with
        a particular email address. You could check like this (where "email" is the database column name and the form
        ID is 10):
	</p>

	{% codemirror php %}
<?php
$api = new FormTools\API();

$criteria = array(
    "email" => $_POST["email"]
);
// note the the $fields variable should be named to whatever your initFormPage() function
// call returns
if (!$api->checkSubmissionIsUnique(10, $criteria, $fields["form_tools_submission_id"])) {
    // uh-oh! A submission already exists with this email address!
    // Abort, abort! here, you could do something like set a
    // variable like: $already_exists = true
    // and in the webpage do a little test to see if it's set.
    // If so, let the user know what's going on
} else {
    // call processFormSubmission() function here to continue processing
    // the form submission
}
?>
	{% endcodemirror %}

	<p class="alert alert-info">
		We chose to use database column names rather than form field names to allow you to also use the system fields
        (is finalized, IP address) to check for uniqueness. You can find the database column names on the Edit Form »
        Fields tab.
	</p>

{% include close_section.html %}