Receive a list of all Testers.

Query Parameters (optional)
email Find a tester by his or her email address.
name Find a tester by his or her name.
page Only the most recent 20 testers will be returned. If you have more than 20 testers you'll need to request all of them in blocks. See Pagination for details.
Please Don't Poll — Instead, use our Webhooks feature, which lets us push data to you when testers are created, updated or deleted. You can set up Webhooks from within the Prefinery UI. If you do decide to poll please note that we impose a rate limit of 60 requests per minute for this API endpoint.

Request

curl https://api.prefinery.com/api/v2/betas/1/testers.json?api_key=secret
      

Response

HTTP/1.1 200 OK

[
  {
    "id": 1,
    "email": "bruce@wayneenterprises.com",
    "status": "invited",
    "invitation_code": "525c22e253",
    "imported_at": null,
    "applied_at": "2012-10-21T16:45:10-05:00",
    "invited_at": "2012-10-22T14:25:10-05:00",
    "joined_at": null,
    "unsubscribed_at": null,
    "share_clicks_count": 0,
    "share_signups_count": 0,
    "friend_invitations_allowed": 5,
    "friend_invitations_count": 0,
    "friend_invitations_remaining": 5,
    "comments_count": 0,
    "share_link": "http://l.aunch.us/FaKElInK",
    "share_status_link": "http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111",
    "waitlist_position": 100,
    "waitlist_ahead": 99,
    "waitlist_behind": 1900,
    "waitlist_length": 2000,
    "referred_by": null,
    "groups": "Investors,Friends",
    "created_at": "2012-10-22T14:25:10-05:00",
    "updated_at": "2012-10-22T14:25:10-05:00",
    "profile": {
      "first_name": "Bruce",
      "last_name": "Wayne",
      "employer": "Wayne Enterprises",
      "jobtitle": "CEO",
      "address_line1": null,
      "address_line2": null,
      "city": "Gotham",
      "state": "NJ",
      "postal_code": "07470",
      "country": "United States",
      "locale": "en-US",
      "telephone": null,
      "gender": "Male",
      "age": "39",
      "facebook_username": null,
      "twitter_username": "bruce",
      "linkedin_username": "brucewayne",
      "browser_name": "Chrome",
      "browser_version": "22.0.1229.79",
      "os_name": "Mac OS X",
      "os_version": "10.8.2",
      "ip": "64.71.141.151",
      "custom_var1": null,
      "custom_var2": null,
      "custom_var3": null,
      "http_referrer": "https://www.google.com"
    }
  }
]
      

Request

curl https://api.prefinery.com/api/v2/betas/1/testers.xml?api_key=secret
      

Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<testers type="array">
  <tester>
    <id type="integer">1</id>
    <email>bruce@wayneenterprises.com</email>
    <status>invited</status>
    <invitation-code>525c22e253</invitation-code>
    <imported-at nil="true"/>
    <applied-at type="datetime">2012-10-21T16:45:10-05:00</applied-at>
    <invited-at type="datetime">2012-10-22T14:25:10-05:00</invited-at>
    <joined-at nil="true"/>
    <unsubscribed-at nil="true"/>
    <share-clicks-count type="integer">0</share-clicks-count>
    <share-signups-count type="integer">0</share-signups-count>
    <friend-invitations-allowed type="integer">5</friend-invitations-allowed>
    <friend-invitations-count type="integer">0</friend-invitations-count>
    <friend-invitations-remaining type="integer">5</friend-invitations-remaining>
    <comments-count type="integer">0</comments-count>
    <share-link>http://l.aunch.us/FaKElInK</share-link>
    <share-status-link>http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111</share-status-link>
    <waitlist-position type="integer">100</waitlist-position>
    <waitlist-ahead type="integer">99</waitlist-ahead>
    <waitlist-behind type="integer">1900</waitlist-behind>
    <waitlist-length type="integer">2000</waitlist-length>
    <referred-by nil="true"/>
    <groups>Investors,Friends</groups>
    <created-at type="datetime">2012-10-22T14:25:10-05:00</created-at>
    <updated-at type="datetime">2012-10-22T14:25:10-05:00</updated-at>
    <profile>
      <first-name>Bruce</first-name>
      <last-name>Wayne</last-name>
      <employer>Wayne Enterprises</employer>
      <jobtitle>CEO</jobtitle>
      <address-line1 nil="true"/>
      <address-line2 nil="true"/>
      <city>Gotham</city>
      <state>NJ</state>
      <postal-code>07470</postal-code>
      <country>United States</country>
      <locale>en-US</locale>
      <telephone nil="true"/>
      <gender>Male</gender>
      <age>39</age>
      <facebook_username></facebook_username>
      <twitter_username>bruce</twitter_username>
      <linkedin_username>brucewayne</linkedin_username>
      <browser-name>Chrome</browser-name>
      <browser-version>22.0.1229.79</browser-version>
      <os-name>Mac OS X</os-name>
      <os-version>10.8.2</os-version>
      <ip>64.71.141.151</ip>
      <custom-var1 nil="true"/>
      <custom-var2 nil="true"/>
      <custom-var3 nil="true"/>
      <http-referrer>https://www.google.com</http-referrer>
    </profile>
  </tester>
</testers>
      

Get a single tester by its ID.

Request

curl https://api.prefinery.com/api/v2/betas/1/testers/1.json?api_key=secret
      

Response

HTTP/1.1 200 OK

{
  "id": 1,
  "email": "bruce@wayneenterprises.com",
  "status": "invited",
  "invitation_code": "525c22e253",
  "imported_at": null,
  "applied_at": "2012-10-21T16:45:10-05:00",
  "invited_at": "2012-10-22T14:25:10-05:00",
  "joined_at": null,
  "unsubscribed_at": null,
  "share_clicks_count": 0,
  "share_signups_count": 0,
  "friend_invitations_allowed": 5,
  "friend_invitations_count": 0,
  "friend_invitations_remaining": 5,
  "comments_count": 0,
  "share_link": "http://l.aunch.us/FaKElInK",
  "share_status_link": "http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111",
  "waitlist_position": 100,
  "waitlist_ahead": 99,
  "waitlist_behind": 1900,
  "waitlist_length": 2000,
  "referred_by": null,
  "groups": "Investors,Friends",
  "created_at": "2012-10-22T14:25:10-05:00",
  "updated_at": "2012-10-22T14:25:10-05:00",
  "profile": {
    "first_name": "Bruce",
    "last_name": "Wayne",
    "employer": "Wayne Enterprises",
    "jobtitle": "CEO",
    "address_line1": null,
    "address_line2": null,
    "city": "Gotham",
    "state": "NJ",
    "postal_code": "07470",
    "country": "United States",
    "locale": "en-US",
    "telephone": null,
    "gender": "Male",
    "age": "39",
    "facebook_username": null,
    "twitter_username": "bruce",
    "linkedin_username": "brucewayne",
    "browser_name": "Chrome",
    "browser_version": "22.0.1229.79",
    "os_name": "Mac OS X",
    "os_version": "10.8.2",
    "ip": "64.71.141.151",
    "custom_var1": null,
    "custom_var2": null,
    "custom_var3": null,
    "http_referrer": "https://www.google.com"
  }
}
      

Request

curl https://api.prefinery.com/api/v2/betas/1/testers/1.xml?api_key=secret
      

Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tester>
  <id type="integer">1</id>
  <email>bruce@wayneenterprises.com</email>
  <status>invited</status>
  <invitation-code>525c22e253</invitation-code>
  <imported-at nil="true"/>
  <applied-at type="datetime">2012-10-21T16:45:10-05:00</applied-at>
  <invited-at type="datetime">2012-10-22T14:25:10-05:00</invited-at>
  <joined-at nil="true"/>
  <unsubscribed-at nil="true"/>
  <share-clicks-count type="integer">0</share-clicks-count>
  <share-signups-count type="integer">0</share-signups-count>
  <friend-invitations-allowed type="integer">5</friend-invitations-allowed>
  <friend-invitations-count type="integer">0</friend-invitations-count>
  <friend-invitations-remaining type="integer">5</friend-invitations-remaining>
  <comments-count type="integer">0</comments-count>
  <share-link>http://l.aunch.us/FaKElInK</share-link>
  <share-status-link>http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111</share-status-link>
  <waitlist-position type="integer">100</waitlist-position>
  <waitlist-ahead type="integer">99</waitlist-ahead>
  <waitlist-behind type="integer">1900</waitlist-behind>
  <waitlist-length type="integer">2000</waitlist-length>
  <referred-by nil="true"/>
  <groups>Investors,Friends</groups>
  <created-at type="datetime">2012-10-22T14:25:10-05:00</created-at>
  <updated-at type="datetime">2012-10-22T14:25:10-05:00</updated-at>
  <profile>
    <first-name>Bruce</first-name>
    <last-name>Wayne</last-name>
    <employer>Wayne Enterprises</employer>
    <jobtitle>CEO</jobtitle>
    <address-line1 nil="true"/>
    <address-line2 nil="true"/>
    <city>Gotham</city>
    <state>NJ</state>
    <postal-code>07470</postal-code>
    <country>United States</country>
    <locale>en-US</locale>
    <telephone nil="true"/>
    <gender>Male</gender>
    <age>39</age>
    <facebook_username></facebook_username>
    <twitter_username>bruce</twitter_username>
    <linkedin_username>brucewayne</linkedin_username>
    <browser-name>Chrome</browser-name>
    <browser-version>22.0.1229.79</browser-version>
    <os-name>Mac OS X</os-name>
    <os-version>10.8.2</os-version>
    <ip>64.71.141.151</ip>
    <custom-var1 nil="true"/>
    <custom-var2 nil="true"/>
    <custom-var3 nil="true"/>
    <http-referrer>https://www.google.com</http-referrer>
  </profile>
</tester>
      

Create a new tester for a particular beta.

Parameter Required? Description
email Required The email address of the tester.
status Optional Choices are:
  • applied — Add the tester and set their status to applied. This is the default.
  • invited — Add the tester, generate a unique invitation code and send an invitation email.
  • active — Add the tester and set their status to active. The active status denotes that the tester is actively participating in your beta (i.e. they have created an account on your site).
  • imported — Just add the tester.
  • unconfirmed — If your project has double opt-in confirmation enabled, add the tester and set their status to unconfirmed.
invitation_code Optional The status must be set to active when setting this field. Populating this field will attempt to validate the invitation code during tester creation and the tester will only be created if this invitation code is valid. The invitation code can be a unique code (tied to the tester's email address) or a custom code (which you created via the UI and is limited by usage or time).
referrer_id Optional Populate this field with the ID or referral code of the referring tester and we will attribute a Referral to that tester. The status must be set to applied or unconfirmed when setting this field. You are responsible for keeping track of the referrer's ID or code, perhaps using cookies. It is highly recommended that you send both the ip and user_agent profile values for all testers created via the API as they are used to combat referral system fraud.
groups Optional A comma separated list of groups (like tagging) to which to add this tester.
profile Optional
  • first_name — The tester's first name.
  • last_name — The tester's last name.
  • employer — Where the tester works.
  • jobtitle — What the tester does.
  • address_line1 — The tester's street address.
  • address_line2 — More street address information.
  • city — The tester's city.
  • state — The tester's state, region or province.
  • postal_code — The tester's postal or zip code.
  • country — The tester's country.
  • locale — The tester's locale. We recommend you pass in your end-user's primary locale, unmodified, in the format language-region (e.g. "en-US") as per RFC5646.
  • telephone — The tester's phone number.
  • gender — The tester's gender — can be Male or Female.
  • age — The tester's age. This is a string.
  • facebook_username — The tester's Facebook username.
  • twitter_username — The tester's Twitter handle.
  • linkedin_username — The tester's LinkedIn username.
  • user_agent — Pass in your end-user's user-agent string, unmodified, and we will attempt to turn this into the individual browser and OS fields shown below. However, we will not overwrite any values you pass into the individual browser and OS fields.
  • browser_name — Web browser name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • browser_version — Web browser version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os_name — Operating system name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os_version — Operating system version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • ip — The end-user's IP address. Sending IP is highly recommended as it is used to combat signup and referral fraud. Also, we will attempt to geolocate the tester and populate the city, state and country values (but won't overwrite any data you pass into these individual location fields).
  • custom_var1 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom_var2 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom_var3 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • http_referrer — Pass in your end-user's HTTP referrer string.
responses Optional The responses to any question's you have added to your Signup Form in the Prefinery UI.
  • question_id — Can be found from within the Prefinery UI by clicking the Edit button next to a particular question.
  • answer — Answers to scale and multiple choice questions begin at a 0 index — meaning the first choice is 0, second choice is 1, etc. For multiple choice questions where more than one choice can be selected, you should submit comma delimited string, such as "0,1" to choose more than one answer. Agreement questions must be answered with 0 (disagree) or 1 (agree).
{
  "tester" : {
    "email": "bruce@wayneenterprises.com",
    "status": "applied",
    "profile": {
      "first_name": "Bruce",
      "last_name": "Wayne",
    },
    "responses": {
      "response": 
      [
        {
          "question_id": "23874", 
          "answer": "a text response"
        },
        {
          "question_id": "23871",
          "answer": "1"
        },
        {
          "question_id": "23872",
          "answer": "0,2"
        },
        {
          "question_id": "23873",
          "answer": "9"
        }
      ]
    }
  }
}
      

Or, using curl:

curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d ' {"tester":{"email":"bruce@wayneenterprises.com","status":"applied","profile":{"first_name": "Bruce", "last_name": "Wayne"},"responses":{"response":[{"question_id":"23874", "answer":"a text response"},{"question_id":"23871", "answer":"1"},{"question_id":"23872", "answer":"0,2"},{"question_id":"23873", "answer":"9"}]}}}' https://api.prefinery.com/api/v2/betas/1/testers.json?api_key=secret
      

Response

HTTP/1.1 201 Created

{
  "id": 1,
  "email": "bruce@wayneenterprises.com",
  "status": "applied",
  "invitation_code": "",
  "imported_at": null,
  "applied_at": "2012-10-21T16:45:10-05:00",
  "invited_at": null,
  "joined_at": null,
  "unsubscribed_at": null,
  "share_clicks_count": 0,
  "share_signups_count": 0,
  "friend_invitations_allowed": 5,
  "friend_invitations_count": 0,
  "friend_invitations_remaining": 5,
  "comments_count": 0,
  "share_link": "http://l.aunch.us/FaKElInK",
  "share_status_link": "http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111",
  "waitlist_position": 100,
  "waitlist_ahead": 99,
  "waitlist_behind": 1900,
  "waitlist_length": 2000,
  "referred_by": null,
  "created_at": "2012-10-22T14:25:10-05:00",
  "updated_at": "2012-10-22T14:25:10-05:00",
  "profile": {
    "first_name": "Bruce",
    "last_name": "Wayne",
    "employer": null,
    "jobtitle": null,
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "state": null,
    "postal_code": null,
    "country": null,
    "locale": null,
    "telephone": null,
    "gender": null,
    "age": null,
    "facebook_username": null,
    "twitter_username": null,
    "linkedin_username": null,
    "browser_name": null,
    "browser_version": null,
    "os_name": null,
    "os_version": null,
    "ip": null,
    "custom_var1": null,
    "custom_var2": null,
    "custom_var3": null,
    "http_referrer": null
  },
  "responses":
    [
      {
        "question_id": 23874,
        "question": "Sentence Question",
        "answer": "a text response"
      },
      {
        "question_id": 23871,
        "question": "Please pick one of the following",
        "answer": "Option 2"
      },
      {
        "question_id": 23872,
        "question": "Please pick any of the following",
        "answer": "Option 1, Option 3"
      },
      {
        "question_id": 23873,
        "question": "Rate this on a scale from 1 to 10",
        "answer": "9"
      }
    ]
}
      
Parameter Required? Description
email Required The email address of the tester.
status Optional Choices are:
  • applied — Add the tester and set their status to applied. This is the default.
  • invited — Add the tester, generate a unique invitation code and send an invitation email.
  • active — Add the tester and set their status to active. The active status denotes that the tester is actively participating in your beta (i.e. they have created an account on your site).
  • imported — Just add the tester.
  • unconfirmed — If your project has double opt-in confirmation enabled, add the tester and set their status to unconfirmed.
invitation-code Optional The status must be set to active when setting this field. Populating this field will attempt to validate the invitation code during tester creation and the tester will only be created if this invitation code is valid. The invitation code can be a unique code (tied to the tester's email address) or a custom code (which you created via the UI and is limited by usage or time).
referrer-id Optional Populate this field with the ID or referral code of the referring tester and we will attribute a Referral to that tester. The status must be set to applied or unconfirmed when setting this field. You are responsible for keeping track of the referrer's ID or code, perhaps using cookies. It is highly recommended that you send both the ip and user_agent profile values for all testers created via the API as they are used to combat referral system fraud.
profile Optional
  • first-name — The tester's first name.
  • last-name — The tester's last name.
  • employer — Where the tester works.
  • jobtitle — What the tester does.
  • address-line1 — The tester's street address.
  • address-line2 — More street address information.
  • city — The tester's city.
  • state — The tester's state, region or province.
  • postal-code — The tester's postal or zip code.
  • country — The tester's country.
  • locale — The tester's locale. We recommend you pass in your end-user's primary locale, unmodified, in the format language-region (e.g. "en-US") as per RFC5646.
  • telephone — The tester's phone number.
  • gender — The tester's gender — can be Male or Female.
  • age — The tester's age. This is a string.
  • facebook-username — The tester's Facebook username.
  • twitter-username — The tester's Twitter handle.
  • linkedin-username — The tester's LinkedIn username.
  • user-agent — Pass in your end-user's user-agent string, unmodified, and we will attempt to turn this into the individual browser and OS fields shown below. However, we will not overwrite any values you pass into the individual browser and OS fields.
  • browser-name — Web browser name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • browser-version — Web browser version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os-name — Operating system name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os-version — Operating system version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • ip — The end-user's IP address. Sending IP is highly recommended as it is used to combat signup and referral fraud. Also, we will attempt to geolocate the tester and populate the city, state and country values (but won't overwrite any data you pass into these individual location fields).
  • custom-var1 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom-var2 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom-var3 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • http-referrer — Pass in your end-user's HTTP referrer string.
responses Optional The responses to any question's you have added to your Signup Form in the Prefinery UI.
  • question-id — Can be found from within the Prefinery UI by clicking the Edit button next to a particular question.
  • answer — Answers to scale and multiple choice questions begin at a 0 index — meaning the first choice is 0, second choice is 1, etc. For multiple choice questions where more than one choice can be selected, you should submit comma delimited string, such as "0,1" to choose more than one answer. Agreement questions must be answered with 0 (disagree) or 1 (agree).
<?xml version="1.0" encoding="UTF-8"?>
<tester>
  <email>bruce@wayneenterprises.com</email>
  <status>applied</status>
  <profile>
    <first-name>Bruce</first-name>
    <last-name>Wayne</last-name>
  </profile>
  <responses>
    <response>
      <question-id>23874</question-id>
      <answer>a text response</answer>
    </response>
    <response>
      <question-id>23871</question-id>
      <answer>1</answer>
    </response>
    <response>
      <question-id>23872</question-id>
      <answer>0,2</answer>
    </response>
    <response>
      <question-id>23873</question-id>
      <answer>9</answer>
    </response>
  </responses>
</tester>
      

Or, using curl:

curl -H "Content-Type: text/xml" --data "<tester><email>bruce@wayneenterprises.com</email><status>applied</status><profile><first-name>Bruce</first-name><last-name>Wayne</last-name></profile><responses><response><question-id>23874</question-id><answer>a text response</answer></response><response><question-id>23871</question-id><answer>1</answer></response><response><question-id>23872</question-id><answer>0,2</answer></response><response><question-id>23873</question-id><answer>9</answer></response></responses></tester>" https://api.prefinery.com/api/v2/betas/1/testers.xml?api_key=secret
      

Response

HTTP/1.1 201 Created

<?xml version="1.0" encoding="UTF-8"?>
<tester>
  <id type="integer">1</id>
  <email>bruce@wayneenterprises.com</email>
  <status>applied</status>
  <invitation-code></invitation-code>
  <imported-at nil="true"/>
  <applied-at type="datetime">2012-10-21T16:45:10-05:00</applied-at>
  <invited-at nil="true"/>
  <joined-at nil="true"/>
  <unsubscribed-at nil="true"/>
  <share-clicks-count type="integer">0</share-clicks-count>
  <share-signups-count type="integer">0</share-signups-count>
  <friend-invitations-allowed type="integer">5</friend-invitations-allowed>
  <friend-invitations-count type="integer">0</friend-invitations-count>
  <friend-invitations-remaining type="integer">5</friend-invitations-remaining>
  <comments-count type="integer">0</comments-count>
  <share-link>http://l.aunch.us/FaKElInK</share-link>
  <share-status-link>http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111</share-status-link>
  <waitlist-position type="integer">100</waitlist-position>
  <waitlist-ahead type="integer">99</waitlist-ahead>
  <waitlist-behind type="integer">1900</waitlist-behind>
  <waitlist-length type="integer">2000</waitlist-length>
  <referred-by nil="true"/>
  <created-at type="datetime">2012-10-22T14:25:10-05:00</created-at>
  <updated-at type="datetime">2012-10-22T14:25:10-05:00</updated-at>
  <profile>
    <first-name>Bruce</first-name>
    <last-name>Wayne</last-name>
    <employer nil="true"/>
    <jobtitle nil="true"/>
    <address-line1 nil="true"/>
    <address-line2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <postal-code nil="true"/>
    <country nil="true"/>
    <locale nil="true"/>
    <telephone nil="true"/>
    <gender nil="true"/>
    <age nil="true"/>
    <facebook-username nil="true"/>
    <twitter-username nil="true"/>
    <linkedin-username nil="true"/>
    <browser-name nil="true"/>
    <browser-version nil="true"/>
    <os-name nil="true"/>
    <os-version nil="true"/>
    <ip nil="true"/>
    <custom-var1 nil="true"/>
    <custom-var2 nil="true"/>
    <custom-var3 nil="true"/>
    <http-referrer nil="true"/>
  </profile>
  <responses type="array">
    <response>
      <question-id type="integer">23874</question-id>
      <question>Text Question</question>
      <answer>a text response</answer>
    </response>
    <response>
      <question-id type="integer">23871</question-id>
      <question>Please pick one of the following</question>
      <answer>Option 2</answer>
    </response>
    <response>
      <question-id type="integer">23872</question-id>
      <question>Please pick any of the following</question>
      <answer>Option 1, Option 3</answer>
    </response>
    <response>
      <question-id type="integer">23873</question-id>
      <question>Rate this on a scale from 1 to 10</question>
      <answer>9</answer>
    </response>
  </responses>
</tester>
      

Errors

Code Description
2301 A general error has occurred.
2302 Email is required.
2303 Name is required.
2304 Employer is required.
2305 Job title is required.
2306 Address is required.
2307 Phone number is invalid.
2308 Answer is required. Typically returned when a required Text, Multiple Choice or Scale question is unanswered.
2309 Must agree. The Agreement question must be answered with a "1" (Agree).
2310 Tester exists. Please use the update method.
2312 Invitation code is invalid or expired.
2313 Invitation code is invalid.
2315 Question not found.
2316 This beta is no longer accepting new applications.
2317 You have exceeded your plan limits and this tester is hidden.
2319 Fraud Protection — Email domain is blacklisted.
2320 Fraud Protection — IP address is blacklisted.
2321 Fraud Protection — Too many signups from this IP address.
2322 We did not receive any data. Often this is a result of sending an incorrect Content-Type header.
2323 IP address is not valid. Please check that you are sending a valid IPv4 address.

Update a single tester by its ID.

Parameter Required? Description
status Optional Choices are: applied invited rejected suspended unsuspended or active

Note: Testers may only transition between certain statuses. Click here to see what status' you can use. Also, any active and associated email messages will be triggered after successfully changing status.

invitation_code Optional The status must be set to active when setting this field. Populating this field will attempt to validate the invitation code during tester update and the tester will only be updated if this invitation code is valid. The invitation code can be a unique code (tied to the tester's email address) or a custom code (which you created via the UI and is limited by usage or time).
groups Optional A comma separated list of groups (like tagging) to which to add this tester.
profile Optional
  • first_name — The tester's first name.
  • last_name — The tester's last name.
  • employer — Where the tester works.
  • jobtitle — What the tester does.
  • address_line1 — The tester's street address.
  • address_line2 — More street address information.
  • city — The tester's city.
  • state — The tester's state, region or province.
  • postal_code — The tester's postal or zip code.
  • country — The tester's country.
  • locale — The tester's locale. We recommend you pass in your end-user's primary locale, unmodified, in the format language-region (e.g. "en-US") as per RFC5646.
  • telephone — The tester's phone number.
  • gender — The tester's gender — can be Male or Female.
  • age — The tester's age. This is a string.
  • facebook_username — The tester's Facebook username.
  • twitter_username — The tester's Twitter handle.
  • linkedin_username — The tester's LinkedIn username.
  • user_agent — Pass in your end-user's user-agent string, unmodified, and we will attempt to turn this into the individual browser and OS fields shown below. However, we will not overwrite any values you pass into the individual browser and OS fields.
  • browser_name — Web browser name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • browser_version — Web browser version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os_name — Operating system name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os_version — Operating system version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • ip — The tester's IP address. We will attempt to geolocate theThe end-user's IP address. Sending IP is highly recommended as it is used to combat signup and referral fraud. Also, we will attempt to geolocate the tester and populate the city, state and country values (but won't overwrite any data you pass into these individual location fields).n> — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom_var2 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom_var3 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • http_referrer — Pass in your end-user's HTTP referrer string.
responses Optional The responses to any question's you have added to your Signup Form in the Prefinery UI.
  • question_id — Can be found from within the Prefinery UI by clicking the Edit button next to a particular question.
  • answer — Answers to scale and multiple choice questions begin at a 0 index — meaning the first choice is 0, second choice is 1, etc. For multiple choice questions where more than one choice can be selected, you should submit comma delimited string, such as "0,1" to choose more than one answer. Agreement questions must be answered with 0 (disagree) or 1 (agree).
{
  "tester" : {
    "status": "applied",
    "profile": {
      "employer": "Wayne Enterprises",
      "jobtitle": "CEO",
    },
    "responses": {
      "response": 
      [
        {
          "question_id": "23874", 
          "answer": "changing my text response"
        }
      ]
    }
  }
}
      

Or, using curl:

curl -H "Accept: application/json" -H "Content-type: application/json" -X PUT -d ' {"tester":{"status":"applied","profile":{"employer": "Wayne Enterprises", "jobtitle": "CEO"},"responses":{"response":[{"question_id":"23874", "answer":"changing my text response"}]}}}' https://api.prefinery.com/api/v2/betas/1/testers/1.json?api_key=secret
      

Response

HTTP/1.1 200 OK

{
  "id": 1,
  "email": "bruce@wayneenterprises.com",
  "status": "applied",
  "invitation_code": "",
  "imported_at": null,
  "applied_at": "2012-10-21T16:45:10-05:00",
  "invited_at": null,
  "joined_at": null,
  "unsubscribed_at": null,
  "share_clicks_count": 0,
  "share_signups_count": 0,
  "friend_invitations_allowed": 5,
  "friend_invitations_count": 0,
  "friend_invitations_remaining": 5,
  "comments_count": 0,
  "share_link": "http://l.aunch.us/FaKElInK",
  "share_status_link": "http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111",
  "waitlist_position": 100,
  "waitlist_ahead": 99,
  "waitlist_behind": 1900,
  "waitlist_length": 2000,
  "referred_by": null,
  "groups": "Investors,Friends",
  "created_at": "2012-10-22T14:25:10-05:00",
  "updated_at": "2012-10-22T14:25:10-05:00",
  "profile": {
    "first_name": "Bruce",
    "last_name": "Wayne",
    "employer": "Wayne Enterprises",
    "jobtitle": "CEO",
    "address_line1": null,
    "address_line2": null,
    "city": null,
    "state": null,
    "postal_code": null,
    "country": null,
    "locale": null,
    "telephone": null,
    "gender": null,
    "age": null,
    "facebook_username": null,
    "twitter_username": null,
    "linkedin_username": null,
    "browser_name": null,
    "browser_version": null,
    "os_name": null,
    "os_version": null,
    "ip": null,
    "custom_var1": null,
    "custom_var2": null,
    "custom_var3": null,
    "http_referrer": null
  },
  "responses":
    [
      {
        "question_id": 23874,
        "question": "Sentence Question",
        "answer": "changing my text response"
      },
      {
        "question_id": 23871,
        "question": "Please pick one of the following",
        "answer": "Option 2"
      },
      {
        "question_id": 23872,
        "question": "Please pick any of the following",
        "answer": "Option 1, Option 3"
      },
      {
        "question_id": 23873,
        "question": "Rate this on a scale from 1 to 10",
        "answer": "9"
      }
    ]
}
      
Parameter Required? Description
status Optional Choices are: applied invited rejected suspended unsuspended or active

Note: Testers may only transition between certain statuses. Click here to see what status' you can use. Also, any active and associated email messages will be triggered after successfully changing status.

invitation-code Optional The status must be set to active when setting this field. Populating this field will attempt to validate the invitation code during tester update and the tester will only be updated if this invitation code is valid. The invitation code can be a unique code (tied to the tester's email address) or a custom code (which you created via the UI and is limited by usage or time).
profile Optional
  • first-name — The tester's first name.
  • last-name — The tester's last name.
  • employer — Where the tester works.
  • jobtitle — What the tester does.
  • address-line1 — The tester's street address.
  • address-line2 — More street address information.
  • city — The tester's city.
  • state — The tester's state, region or province.
  • postal-code — The tester's postal or zip code.
  • country — The tester's country.
  • locale — The tester's locale. We recommend you pass in your end-user's primary locale, unmodified, in the format language-region (e.g. "en-US") as per RFC5646.
  • telephone — The tester's phone number.
  • gender — The tester's gender — can be Male or Female.
  • age — The tester's age. This is a string.
  • facebook-username — The tester's Facebook username.
  • twitter-username — The tester's Twitter handle.
  • linkedin-username — The tester's LinkedIn username.
  • user-agent — Pass in your end-user's user-agent string, unmodified, and we will attempt to turn this into the individual browser and OS fields shown below. However, we will not overwrite any values you pass into the individual browser and OS fields.
  • browser-name — Web browser name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • browser-version — Web browser version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os-name — Operating system name. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • os-version — Operating system version. We recommend you pass in your end-user's user-agent string, unmodified, instead of setting this field.
  • ip — The tester's IP address. We will attempt to geolocate theThe end-user's IP address. Sending IP is highly recommended as it is used to combat signup and referral fraud. Also, we will attempt to geolocate the tester and populate the city, state and country values (but won't overwrite any data you pass into these individual location fields).n> — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom-var2 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • custom-var3 — A custom string which will be made available to Email Messages, Webhooks and API requests.
  • http-referrer — Pass in your end-user's HTTP referrer string.
responses Optional The responses to any question's you have added to your Signup Form in the Prefinery UI.
  • question-id — Can be found from within the Prefinery UI by clicking the Edit button next to a particular question.
  • answer — Answers to scale and multiple choice questions begin at a 0 index — meaning the first choice is 0, second choice is 1, etc. For multiple choice questions where more than one choice can be selected, you should submit comma delimited string, such as "0,1" to choose more than one answer. Agreement questions must be answered with 0 (disagree) or 1 (agree).
<?xml version="1.0" encoding="UTF-8"?>
<tester>
  <status>applied</status>
  <profile>
    <employer>Wayne Enterprises</employer>
    <jobtitle>CEO</jobtitle>
  </profile>
  <responses>
    <response>
      <question-id>23874</question-id>
      <answer>changing my text response</answer>
    </response>
  </responses>
</tester>
      

Or, using curl:

curl -H "Content-Type: text/xml" --data "<tester><status>applied</status><profile><employer>Wayne Enterprises</employer><jobtitle>CEO</jobtitle></profile><responses><response><question-id>23874</question-id><answer>changing my text response</answer></response></responses></tester>" https://api.prefinery.com/api/v2/betas/1/testers/1.xml?api_key=secret
      

Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tester>
  <id type="integer">1</id>
  <email>bruce@wayneenterprises.com</email>
  <status>applied</status>
  <invitation-code></invitation-code>
  <imported-at nil="true"/>
  <applied-at type="datetime">2012-10-21T16:45:10-05:00</applied-at>
  <invited-at nil="true"/>
  <joined-at nil="true"/>
  <unsubscribed-at nil="true"/>
  <share-clicks-count type="integer">0</share-clicks-count>
  <share-signups-count type="integer">0</share-signups-count>
  <friend-invitations-allowed type="integer">5</friend-invitations-allowed>
  <friend-invitations-count type="integer">0</friend-invitations-count>
  <friend-invitations-remaining type="integer">5</friend-invitations-remaining>
  <comments-count type="integer">0</comments-count>
  <share-link>http://l.aunch.us/FaKElInK</share-link>
  <share-status-link>http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111</share-status-link>
  <waitlist-position type="integer">100</waitlist-position>
  <waitlist-ahead type="integer">99</waitlist-ahead>
  <waitlist-behind type="integer">1900</waitlist-behind>
  <waitlist-length type="integer">2000</waitlist-length>
  <referred-by nil="true"/>
  <groups>Investors,Friends</groups>
  <created-at type="datetime">2012-10-22T14:25:10-05:00</created-at>
  <updated-at type="datetime">2012-10-22T14:25:10-05:00</updated-at>
  <profile>
    <first-name>Bruce</first-name>
    <last-name>Wayne</last-name>
    <employer>Wayne Enterprises</employer>
    <jobtitle>CEO</jobtitle>
    <address-line1 nil="true"/>
    <address-line2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <postal-code nil="true"/>
    <country nil="true"/>
    <locale nil="true"/>
    <telephone nil="true"/>
    <gender nil="true"/>
    <age nil="true"/>
    <facebook-username nil="true"/>
    <twitter-username nil="true"/>
    <linkedin-username nil="true"/>
    <browser-name nil="true"/>
    <browser-version nil="true"/>
    <os-name nil="true"/>
    <os-version nil="true"/>
    <ip nil="true"/>
    <custom-var1 nil="true"/>
    <custom-var2 nil="true"/>
    <custom-var3 nil="true"/>
    <http-referrer nil="true"/>
  </profile>
  <responses type="array">
    <response>
      <question-id type="integer">23874</question-id>
      <question>Text Question</question>
      <answer>changing my text response</answer>
    </response>
    <response>
      <question-id type="integer">23871</question-id>
      <question>Please pick one of the following</question>
      <answer>Option 2</answer>
    </response>
    <response>
      <question-id type="integer">23872</question-id>
      <question>Please pick any of the following</question>
      <answer>Option 1, Option 3</answer>
    </response>
    <response>
      <question-id type="integer">23873</question-id>
      <question>Rate this on a scale from 1 to 10</question>
      <answer>9</answer>
    </response>
  </responses>
</tester>
      

Errors

Code Description
2301 A general error has occurred.
2302 Email is required.
2303 Name is required.
2304 Employer is required.
2305 Job title is required.
2306 Address is required.
2307 Phone number is invalid.
2308 Answer is required. Typically returned when a required Text, Multiple Choice or Scale question is unanswered.
2309 Must agree. The Agreement question must be answered with a "1" (Agree).
2315 Question not found.
2316 This beta is no longer accepting new applications.
2317 You have exceeded your plan limits and this tester is hidden.
2323 IP address is not valid. Please check that you are sending a valid IPv4 address.

Delete a single tester by its ID.

Parameters (optional)
queue=true Queue the tester for deletion and return immediately. Recommended if you want a very fast response and don't need the tester to be immediately deleted. With this parameter present you will receive a HTTP 202 Accepted response.

Request

curl -X DELETE https://api.prefinery.com/api/v2/betas/1/testers/1.json?api_key=secret
      

Response

HTTP/1.1 200 OK
      

Request

curl -X DELETE https://api.prefinery.com/api/v2/betas/1/testers/1.xml?api_key=secret
      

Response

HTTP/1.1 200 OK
      

Errors

Code Description
2301 A general error has occurred.
2311 Unable to delete tester.
2317 You have exceeded your plan limits and this tester is hidden.

Verify whether an invitation code is valid for a given tester.

Query Parameters
invitation_code The invitation code to validate against.

Request

curl https://api.prefinery.com/api/v2/betas/1/testers/1/verify.json?api_key=secret&invitation_code=525c22e253
      

Response

HTTP/1.1 200 OK

{
  "id": 1,
  "email": "bruce@wayneenterprises.com",
  "status": "invited",
  "invitation_code": "525c22e253",
  "imported_at": null,
  "applied_at": "2012-10-21T16:45:10-05:00",
  "invited_at": "2012-10-22T14:25:10-05:00",
  "joined_at": null,
  "unsubscribed_at": null,
  "share_clicks_count": 0,
  "share_signups_count": 0,
  "friend_invitations_allowed": 5,
  "friend_invitations_count": 0,
  "friend_invitations_remaining": 5,
  "comments_count": 0,
  "share_link": "http://l.aunch.us/FaKElInK",
  "share_status_link": "http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111",
  "waitlist_position": 100,
  "waitlist_ahead": 99,
  "waitlist_behind": 1900,
  "waitlist_length": 2000,
  "referred_by": null,
  "created_at": "2012-10-22T14:25:10-05:00",
  "updated_at": "2012-10-22T14:25:10-05:00",
  "profile": {
    "first_name": "Bruce",
    "last_name": "Wayne",
    "employer": "Wayne Enterprises",
    "jobtitle": "CEO",
    "address_line1": null,
    "address_line2": null,
    "city": "Gotham",
    "state": "NJ",
    "postal_code": "07470",
    "country": "United States",
    "locale": "en-US",
    "telephone": null,
    "gender": "Male",
    "age": "39",
    "facebook_username": null,
    "twitter_username": "bruce",
    "linkedin_username": "brucewayne",
    "browser_name": "Chrome",
    "browser_version": "22.0.1229.79",
    "os_name": "Mac OS X",
    "os_version": "10.8.2",
    "ip": "64.71.141.151"
  }
}
      

Request

curl https://api.prefinery.com/api/v2/betas/1/testers/1/verify.xml?api_key=secret&invitation_code=525c22e253
      

Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tester>
  <id type="integer">1</id>
  <email>bruce@wayneenterprises.com</email>
  <status>invited</status>
  <invitation-code>525c22e253</invitation-code>
  <imported-at nil="true"/>
  <applied-at type="datetime">2012-10-21T16:45:10-05:00</applied-at>
  <invited-at type="datetime">2012-10-22T14:25:10-05:00</invited-at>
  <joined-at nil="true"/>
  <unsubscribed-at nil="true"/>
  <share-clicks-count type="integer">0</share-clicks-count>
  <share-signups-count type="integer">0</share-signups-count>
  <friend-invitations-allowed type="integer">5</friend-invitations-allowed>
  <friend-invitations-count type="integer">0</friend-invitations-count>
  <friend-invitations-remaining type="integer">5</friend-invitations-remaining>
  <comments-count type="integer">0</comments-count>
  <share-link>http://l.aunch.us/FaKElInK</share-link>
  <share-status-link>http://l.aunch.us/FaKElInK?check=11111111-1111-1111-1111-111111111111</share-status-link>
  <waitlist-position type="integer">100</waitlist-position>
  <waitlist-ahead type="integer">99</waitlist-ahead>
  <waitlist-behind type="integer">1900</waitlist-behind>
  <waitlist-length type="integer">2000</waitlist-length>
  <referred-by nil="true"/>
  <created-at type="datetime">2012-10-22T14:25:10-05:00</created-at>
  <updated-at type="datetime">2012-10-22T14:25:10-05:00</updated-at>
  <profile>
    <first-name>Bruce</first-name>
    <last-name>Wayne</last-name>
    <employer></employer>
    <jobtitle></jobtitle>
    <address-line1 nil="true"/>
    <address-line2 nil="true"/>
    <city>Gotham</city>
    <state>NJ</state>
    <postal-code>07470</postal-code>
    <country>United States</country>
    <locale>en-US</locale>
    <telephone nil="true"/>
    <gender>Male</gender>
    <age>39</age>
    <facebook_username></facebook_username>
    <twitter_username>bruce</twitter_username>
    <linkedin_username>brucewayne</linkedin_username>
    <browser-name>Chrome</browser-name>
    <browser-version>22.0.1229.79</browser-version>
    <os-name>Mac OS X</os-name>
    <os-version>10.8.2</os-version>
    <ip>64.71.141.151</ip>
  </profile>
</tester>
      

Errors

Code Description
2301 A general error has occurred.
2312 Invitation code is invalid or expired.
2317 You have exceeded your plan limits and this tester is hidden.

When a tester checks in their status will be set to active. Checking in a tester who has created an account on your site is a great way to identify testers who have actually accepted the invitation to your beta. Also, checking in a tester each time they log into your site is a great way to track visits and retention over time.

If you want to check in a tester by e-mail address, see Checkins

Request

      curl -X POST https://api.prefinery.com/api/v2/betas/1/testers/1/checkin.json?api_key=secret
      

Response

HTTP/1.1 202 Accepted
      

Request

      curl -X POST https://api.prefinery.com/api/v2/betas/1/testers/1/checkin.xml?api_key=secret
      

Response

HTTP/1.1 202 Accepted
      

Receive a list of checkins for a given tester. Only the last 60 checkins are returned and only one checkin is recorded per day.

Request

curl https://api.prefinery.com/api/v2/betas/1/testers/1/checkins.json?api_key=secret
      

Response

HTTP/1.1 200 OK

[
  {
    "date": "2012-10-22",
    "date": "2012-10-20",
    "date": "2012-10-17"
  }
]
      

Request

curl https://api.prefinery.com/api/v2/betas/1/testers/1/checkins.xml?api_key=secret
      

Response

HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<checkins type="array">
  <checkin>
    <date type="date">2012-10-22</date>
  </checkin>
  <checkin>
    <date type="date">2012-10-20</date>
  </checkin>
  <checkin>
    <date type="date">2012-10-17</date>
  </checkin>
</checkins>