Users (aka Testers)

Users or Testers? They're the same thing, and represent the people who are participating in your prelaunch or referral campaigns. We used to say testers, now we say users. A future version of the API will use the term users.

LIST all testers GET /api/v2/betas/{beta_id}/testers

Receive a list of all Testers.

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, per project, and 180 requests per minute for this API endpoint, cummulative, for all projects in your company account.

Parameters

email_is optional
Find testers by email address, using an exact match search.
email_contains optional
Find testers by email address, using a fuzzy search (e.g. "@gmail.com").
name optional
Find testers by name. Will search for matches of first_name and/or last_name.
referral_code optional
Find testers by referral code, using an exact match search.
custom_vars optional
Find testers by contents of any of the three custom variable fields. Will search for exact matches of custom_var1, custom_var2 or custom_var3.

Request

    
curl -u api_key: https://api.prefinery.com/api/v2/betas/1/testers.json

Response

    
  HTTP/1.1 200 OK

  [
    {
      "id": 1,
      "email": "leonard@bigbangtheory.com",
      "status": "invited",
      "invitation_code": "525c22e253",
      "imported_at": null,
      "applied_at": "2012-10-21T16:45:10Z",
      "invited_at": "2012-10-22T14:25:10Z",
      "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,
      "referral_code": "FaKElInK",
      "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:10Z",
      "updated_at": "2012-10-22T14:25:10Z",
      "profile": {
        "first_name": "Leonard",
        "last_name": "Hofstadter",
        "employer": "Caltech",
        "jobtitle": "Experimental Physicist",
        "address_line1": null,
        "address_line2": null,
        "city": "Pasadena",
        "state": "CA",
        "postal_code": "91125",
        "country": "United States",
        "locale": "en-US",
        "telephone": null,
        "gender": "Male",
        "age": "39",
        "facebook_username": null,
        "twitter_username": "leonard",
        "linkedin_username": "leonard",
        "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",
        "utm_source": "Google",
        "utm_medium": "cpc",
        "utm_campaign": "comiccon",
        "utm_term": "san+diego+2018",
        "utm_content": "banner"
      }
    }
  ]

SHOW a tester GET /api/v2/betas/{beta_id}/testers/1

Get a single tester by its ID.

Request

    
curl -u api_key: https://api.prefinery.com/api/v2/betas/1/testers/1.json

Response

    
  HTTP/1.1 200 OK

  {
    "id": 1,
    "email": "leonard@bigbangtheory.com",
    "status": "invited",
    "invitation_code": "525c22e253",
    "imported_at": null,
    "applied_at": "2012-10-21T16:45:10Z",
    "invited_at": "2012-10-22T14:25:10Z",
    "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,
    "referral_code": "FaKElInK",
    "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:10Z",
    "updated_at": "2012-10-22T14:25:10Z",
    "profile": {
      "first_name": "Leonard",
      "last_name": "Hofstadter",
      "employer": "Caltech",
      "jobtitle": "Experimental Physicist",
      "address_line1": null,
      "address_line2": null,
      "city": "Pasadena",
      "state": "CA",
      "postal_code": "91125",
      "country": "United States",
      "locale": "en-US",
      "telephone": null,
      "gender": "Male",
      "age": "39",
      "facebook_username": null,
      "twitter_username": "leonard",
      "linkedin_username": "leonard",
      "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",
      "utm_source": "Google",
      "utm_medium": "cpc",
      "utm_campaign": "comiccon",
      "utm_term": "san+diego+2018",
      "utm_content": "banner"
    }
  }

CREATE a new tester POST /api/v2/betas/{beta_id}/testers

Create a new tester for a particular beta.

Parameter Required? Description
email Required The person's email address.
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 person'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 either the ID, referral code, or email address of the referring tester and we will attribute a referral to that person.

Note: The status must be set to applied or unconfirmed when setting this field. Also, 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 (called tags inside your account) to which to add this tester.
profile Optional
  • first_name — The person's first name.
  • last_name — The person's last name.
  • employer — Where the person works.
  • jobtitle — What the person does.
  • address_line1 — Address line 1 (e.g., street, PO Box, or company name).
  • address_line2 — Address line 2 (e.g., apartment, suite, unit, or building).
  • city — City, district, suburb, town, or village.
  • state — State, county, province, or region.
  • postal_code — ZIP or postal code.
  • country — Two-letter country code (ISO 3166-1 alpha-2).
  • locale — The user's locale, in the format language-region (e.g. "en-US") as per RFC5646.
  • telephone — The person's phone number.
  • gender — The person's gender — can be Male or Female.
  • age — The person's age. This is a string.
  • facebook_username — The person's Facebook username.
  • twitter_username — The person's Twitter handle.
  • linkedin_username — The person's LinkedIn username.
  • user_agent — Pass in the person'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. Sending user agent is highly recommended as it is used to combat fraud.
  • browser_name — Web browser name. We recommend you pass in the person's user agent string, unmodified, instead of setting this field.
  • browser_version — Web browser version. We recommend you Pass in the person's user agent string, unmodified, instead of setting this field.
  • os_name — Operating system name. We recommend you pass in the person's user agent string, unmodified, instead of setting this field.
  • os_version — Operating system version. We recommend you Pass in the person's user agent string, unmodified, instead of setting this field.
  • ip — The person's IP address (IPv4). 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). Sending IP is highly recommended as it is used to combat fraud.
  • 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 — The address of the webpage the person was on prior to landing on your site.
  • utm_source — UTM Source string.
  • utm_medium — UTM Medium string.
  • utm_campaign — UTM Campaign string.
  • utm_term — UTM Term string.
  • utm_content — UTM Content 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).

Request

Note: — Please be sure to wrap your request in the "tester":{} object, as shown below: 

    
  {
    "tester" : {
      "email": "leonard@bigbangtheory.com",
      "status": "applied",
      "profile": {
        "first_name": "Leonard",
        "last_name": "Hofstadter",
      },
      "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: 

    
    # Simple
    curl -u api_key: https://api.prefinery.com/api/v2/betas/1/testers.json \
      -d tester[email]=leonard@bigbangtheory.com \
      -d tester[status]=applied \
      -d tester[profile][first_name]=Leonard \
      -d tester[profile][last_name]=Hofstadter

    # Extended
    curl -X POST -d '{"tester":{"email":"leonard@bigbangtheory.com","status":"applied","profile":{"first_name": "Leonard", "last_name": "Hofstadter"},"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"}]}}}' -u api_key: https://api.prefinery.com/api/v2/betas/1/testers.json

Response

    
  HTTP/1.1 201 Created

  {
    "id": 1,
    "email": "leonard@bigbangtheory.com",
    "status": "applied",
    "invitation_code": "",
    "imported_at": null,
    "applied_at": "2012-10-21T16:45:10Z",
    "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,
    "referral_code": "FaKElInK",
    "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,
    "created_at": "2012-10-22T14:25:10Z",
    "updated_at": "2012-10-22T14:25:10Z",
    "profile": {
      "first_name": "Leonard",
      "last_name": "Hofstadter",
      "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,
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": 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"
        }
      ]
  }

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.
2325 Country is required.
2307 Phone number is invalid.
2308 Answer is required. Typically returned when a required Text, Multiple Choice or Scale question is unanswered.
2324 Answer is invalid.
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 project is no longer accepting new signups.
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 or not wrapping your request data in the "tester":{} object.
2323 IP address is not valid. Please check that you are sending a valid IPv4 address.

UPDATE a tester PUT /api/v2/betas/{beta_id}/testers/1

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 person'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 either the ID, referral code, or email address of the referring tester and we will attribute a referral to that person.
groups Optional A comma separated list of groups (called tags inside your account) to which to add this tester.
profile Optional
  • first_name — The person's first name.
  • last_name — The person's last name.
  • employer — Where the person works.
  • jobtitle — What the person does.
  • address_line1 — Address line 1 (e.g., street, PO Box, or company name).
  • address_line2 — Address line 2 (e.g., apartment, suite, unit, or building).
  • city — City, district, suburb, town, or village.
  • state — State, county, province, or region.
  • postal_code — ZIP or postal code.
  • country — Two-letter country code (ISO 3166-1 alpha-2).
  • locale — The user's locale, in the format language-REGION (e.g. "en-US") as per RFC5646.
  • telephone — The person's phone number.
  • gender — The person's gender — can be Male or Female.
  • age — The person's age. This is a string.
  • facebook_username — The person's Facebook username.
  • twitter_username — The person's Twitter handle.
  • linkedin_username — The person's LinkedIn username.
  • user_agent — Pass in the person'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 the person's user agent string, unmodified, instead of setting this field.
  • browser_version — Web browser version. We recommend you Pass in the person's user agent string, unmodified, instead of setting this field.
  • os_name — Operating system name. We recommend you pass in the person's user agent string, unmodified, instead of setting this field.
  • os_version — Operating system version. We recommend you Pass in the person's user agent string, unmodified, instead of setting this field.
  • ip — The person's IP address (IPv4). 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 — The address of the webpage the person was on prior to landing on your site.
  • utm_source — UTM Source string.
  • utm_medium — UTM Medium string.
  • utm_campaign — UTM Campaign string.
  • utm_term — UTM Term string.
  • utm_content — UTM Content 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).

Request

    
  {
    "tester" : {
      "status": "applied",
      "profile": {
        "employer": "Caltech",
        "jobtitle": "Experimental Physicist",
      },
      "responses": {
        "response": 
        [
          {
            "question_id": "23874", 
            "answer": "changing my text response"
          }
        ]
      }
    }
  }

Or, using curl: 

    
curl -u api_key: -X PUT -d '{"tester":{"status":"applied","profile":{"employer": "Caltech", "jobtitle": "Experimental Physicist"},"responses":{"response":[{"question_id":"23874", "answer":"changing my text response"}]}}}' https://api.prefinery.com/api/v2/betas/1/testers/1.json

Response

    
  HTTP/1.1 200 OK

  {
    "id": 1,
    "email": "leonard@bigbangtheory.com",
    "status": "applied",
    "invitation_code": "",
    "imported_at": null,
    "applied_at": "2012-10-21T16:45:10Z",
    "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,
    "referral_code": "FaKElInK",
    "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:10Z",
    "updated_at": "2012-10-22T14:25:10Z",
    "profile": {
      "first_name": "Leonard",
      "last_name": "Hofstadter",
      "employer": "Caltech",
      "jobtitle": "Experimental Physicist",
      "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,
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": 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"
        }
      ]
  }

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.
2325 Country 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 project is no longer accepting new signups.
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 tester DELETE /api/v2/betas/{beta_id}/testers/1

Delete a single tester by its ID.

Parameters

queue optional boolean
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. Defaults to false.

Request

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

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 an invite code GET /api/v2/betas/{beta_id}/testers/1/verify

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

Parameters

invitation_code required
The invitation code to validate against.

Request

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

Response

    
  HTTP/1.1 200 OK

  {
    "id": 1,
    "email": "leonard@bigbangtheory.com",
    "status": "invited",
    "invitation_code": "525c22e253",
    "imported_at": null,
    "applied_at": "2012-10-21T16:45:10Z",
    "invited_at": "2012-10-22T14:25:10Z",
    "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,
    "referral_code": "FaKElInK",
    "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:10Z",
    "updated_at": "2012-10-22T14:25:10Z",
    "profile": {
      "first_name": "Leonard",
      "last_name": "Hofstadter",
      "employer": "Caltech",
      "jobtitle": "Experimental Physicist",
      "address_line1": null,
      "address_line2": null,
      "city": "Pasadena",
      "state": "CA",
      "postal_code": "91125",
      "country": "United States",
      "locale": "en-US",
      "telephone": null,
      "gender": "Male",
      "age": "39",
      "facebook_username": null,
      "twitter_username": "leonard",
      "linkedin_username": "leonard",
      "browser_name": "Chrome",
      "browser_version": "22.0.1229.79",
      "os_name": "Mac OS X",
      "os_version": "10.8.2",
      "ip": "64.71.141.151"
    }
  }

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.

CHECKIN a tester POST /api/v2/betas/{beta_id}/testers/1/checkin

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 -u api_key: -X POST https://api.prefinery.com/api/v2/betas/1/testers/1/checkin.json

Response

    
HTTP/1.1 202 Accepted

LIST CHECKINS GET /api/v2/betas/{beta_id}/testers/1/checkins

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 -u api_key: https://api.prefinery.com/api/v2/betas/1/testers/1/checkins.json

Response

    
  HTTP/1.1 200 OK

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