Prospects

This endpoint is used to manage prospective new users (or applicants). Their data is validated and, if appropriate, they are converted to users.

Endpoint	Action
/prospect/data	Submit data from or about a prospect.
/prospect/registration	Register a device to be used by this prospect.
/prospect/image	Upload an image for a prospect.
/recovery/code	Generate a random recovery code for a device.
/confirm/mobile/:AFiUserId/:confirmationCodeMobile	Confirm a prospect's mobile number.
/confirm/email/:AFiUserId/:confirmationCodeEmail	Confirm a prospect's email address.
/disavow/email/:AFiUserId/:recipientEmailB64	Disavow or unconfirm an email address. The email address will no longer be honored. However it may be recovered at a later time.
/harden/:AFiUserId/:recipientEmailB64	Disavow an email address and ensure that it cannot be recovered.
/prospect/generic	Present an arbitrary request that will be interpreted by the system for a specific user.
/prospect/connectsocket	Requests authorization of a websocket connection to enable efficient 2-way communication with this prospect.

Submit data

Request method and URL

POST /prospect/data

Description

This API is used to submit data from or about a prospect. Typical data is shown in the request body example. The actual data can vary widely.

Required Properties	Description	Schema	Example Values
deviceTag	The device id (provided by user)	string	"o1vd1oc0nw8"
preSegment	The original category of prospect (ex. "teacher", "adult")	string	"demo_uoiuqwehflkipahgoqq"
deviceData	A device-specific set of data	object	{ //See deviceData Object below }
payload	A segment-specific set of data required to register the user; e.g. name, address, and other personal info	object	{ //See payload Object below }

Optional Properties	Description	Schema	Example Values
referral	A code from a friend	string	"BBQFCHQXN"
dtsCollected	The current date and time	string	"2022-06-20T15:33:22.726Z"
deepLink	A code with which family members get linked to each other	string, nullable	"null"
linkinjected	A link to another user	string, nullable	"null"
ipAddress	The device IP address	string	"::ffff:127.0.0.1"

payload Object Example

This is an example payload and may differ depending on the user segment.

Properties	Description	Schema	Example Values
name	The user's name	object	{ "firstName": "John", "middleName": "", "lastName": "Testman" }
address	The user's main address	object	{ "addressLine1": "123 Main Str.", "city": "Harrisburg", "state": "PA", "postalCode": "12345", "countryCode": "US"}
address1	Additional user address details	object	{ "countryCode": "US" }
dob	The user's date of birth	object	{ "dts": "1978-10-15T17:12:25.000+00:00", "day": 15, "month": 10, "year": 1978 }
document	An identification document information object, such as for SSN or Driver's License	object	{ "type": "US driving license", "number": "123456789", "issued": "10052015", "expires": "10052025", "issuingState": "PA" }
extra	An object containing any additional information that was requested	object	{ "sex": "male", "eyeColor": "BRO", "hairColor": "BLK", "heightMetric": "181", "weightMetric": "185"}
ssn	The user's Social Security Number (for US)	string	"123456789"
mobile	The user's mobile phone number	string	"1234567890"
email	The user's email address	string	"aa@aa.ae"
languageCode	The user's primary language or device language	string	"en"

deviceData Object

Properties	Description	Schema	Example Values
platform	The device platform	string	"android"
build	The device platform build version	string	"0.0.01"

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

  {
    "deviceTag": "o1vd1oc0nw8", //device id (provided by user) 
    "dtsCollected": "2022-06-20T15:33:22.726Z", //current date and time
    "preSegment": "demo_uoiuqwehflkipahgoqq", //original category of prospect (ex. "teacher", "adult")
    "linkinjected": "null", //link to another user (optional)
    "payload": { //segment-specific set of data required to register the user; e.g. name, address, and other personal info 
      "referrerAFiUserId": "qweaurl4zdpfo2hu"
    }, 
    "deviceData": {  //device-specific set of data  
        "platform": "android",
        "build": "0.0.01"
    },
    "deepLink": "null", //A code with which family members get linked to each other (optional)
    "referral": "BBQFCHQXN", //A code from a friend  (optional)
    "ipAddress": "::ffff:127.0.0.1", //device IP address  (optional)
  }

Response body example

  {
    "success": true
  }

Possible Errors

Status Code	Description of possible error
404	Thrown if any of the following is true: Not enough parameters in the request body, Error recording data from a prospect, Failed storing prospects data, No deviceTag given, No preSegment given, or No path from preSegment to a segment

Back to Top

Registration

Request method and URL

POST /prospect/registration

Description

This API is used to register a device to be used by this prospect. Either an existing user could be trying to register a new device or a completely new prospect (not yet a user) could be registering a device.

If the registration request is made by an existing user, the preSegment value will be "recovery". If registration is successful, the IP address of the new device is recorded in the database.

If the registration request is made by a prospect that is not a pre-existing user, the prospect will first be converted to an idle user and then to a user.

In order to convert to an idle user, first an ampliFi user object is created. A random AFiUserId will be generated and the database will be checked to verify that the AFiUserId is unique. The ampliFi user object (see example below) will be inserted into the ampliFi database and the new user's deviceTag will be marked as registered.

For a prospect (to new user) registration, after the new ampliFi user object is successfully inserted into the ampliFi database, the new user registration must be finalized. If the new user has a referral code, a task will be registered with the referree AFiUserId and the associated referral code so that a referral bonus can be paid to the referree.

Required Properties	Description	Schema	Example Values
deviceTag	The device id (provided by user)	string	"o1vd1oc0nw8"
preSegment	The original category of prospect (ex. "recovery", "teacher", "adult")	string	"demo_uoiuqwehflkipahgoqq"
deviceData	A device-specific set of data	object	{ //See deviceData Object in the Submit data section above }

Optional Properties	Description	Schema	Example Values
referral	A code from a friend	string	"BBQFCHQXN"

ampliFi user object example for new user

{
    "AFiUserId": "qweaurl8kgtlv9pc", //randomly generated and unique id
    "dtsCreated": "2022-09-27T17:22:03.172Z",
    "names": [],
    "name": {
        "firstName": ""
    },
    "firstName": "",
    "sortId": "s7j", //randomly generated
    "languageCode": "en", //defaults to english, other possible values are "fr" (French) or "es" (Spanish)
    "dtsCreated": "2022-09-27T17:22:03.172Z",
    "dtsModified": "2022-09-27T17:22:03.172Z",
    "dtsCreatedAtUsers": "2022-09-27T17:22:03.172Z",
    "segment": "demo", //given presegment is converted into the corresponding idle user segment and then to a finalized user
    "postOnboardingStepsRequired": "postonboardingadultstep2", //or "welcome", etc. 
    "referralCode": "BBBUTHZFE", //unique referral code generated if new user will be allowed to make referrals, otherwise referralCode defaults to undefined
    "extras": {},
    "private": true, //not a company, a private person
    "isFullyRegistered": false, //updates to true when finalized
    "isIdleUser": true, //updates to false if finalized user segment is not idle
    "uiStage": undefined //updates to "firstContact" when finalized as a user
    //"requirements": { //an object containing required ID image type sets (user must provide at least one valid combination of user ID documents), this property is added when user is finalized }
}

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

  {
    "preSegment": "demo_uoiuqwehflkipahgoqq", //original category of prospect (ex. "recovery", "teacher", "adult")
    "deviceData": { //device-specific set of data
        "platform": "android",
        "build": "0.0.01"
    },
    "deviceTag": "o1vd1oc0nw8", //user-generated device id 
    "referral": "BBQFCHQXN" //A code from a friend  (optional)
  }

Response body example

{
    "success": true, //Success
    "segment": "demo", //user segment after the prospect has been converted to a final user segment
    "serverSecret": "a long random string" //a server secret that was randomly generated and can be used to verify that the device being used was registered by the user
}

Possible Errors

Status Code	Description of possible error
401	If deviceData, deviceTag, or preSegment are missing, this error is thrown and the actor is locked for a specified time period. Also thrown if the actor (user) is currently locked and attempts device registration before a set time period has passed.
404	ERROR: Attempt to recover a hardened user. The hardened user data is sent to the operator with a notification that recovery of a hardened user was attempted.
500	Thrown if system failed converting prospect into user or failed storing serverSecret.
400+	Other possible error messages that may appear are: "Failed finding user for recovery", "Unknown preSegment", "User appears to be trying to register (convert prospect into a user) and supplied preSegment is unknown."

Back to Top

Upload image

Request method and URL

POST /prospect/image

Description

Upload an image for a prospect. The image may be a driver's license, a passport, or a face image. It should be in a common file format such as png. The image is base 64 encoded.

Required Properties	Description	Schema	Example Values
deviceTag	The device id (provided by user)	string	"o1vd1oc0nw8"
imageBase64	The image itself, base 64 encoded	string	"very long base 64 encrypted string"
AFiImageId	user-generated image id	string	"l4mwddbcgiu0hq1h0gp"

Optional Properties	Description	Schema	Example Values
preSegment	The original category of prospect (ex. "recovery", "teacher", "adult")	string	"demo_uoiuqwehflkipahgoqq"
type	The image type	string	"Face image"
dtsCreated	Date/time stamp at user's end	string	"2022-06-20T15:33:22.529+00:00"

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

  {
    "deviceTag": "o1vd1oc0nw8", //user-generated device id 
    "AFiImageId": "l4mwddbcgiu0hq1h0gp", //user-generated image id 
    "type": "Face image", //image type  
    "imageBase64": "/9j/2wBDAAY...BsJ8CBbkwxGZUJzKKP/Z", //image itself, base 64 encoded
    "dtsCreated": "2022-06-20T15:33:22.529+00:00" //dts at user's end
  }

Response body example

  {
    "success": true
  }

Possible Errors

Status Code	Description of possible error
404	Not enough parameters in the request body, Error recording a document image from a prospect
400+	Failed storing prospects image

Back to Top

Recovery code

Request method and URL

POST /recovery/code

Description

Generate a random recovery code for a device

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

  {
    "deviceTag": "o1vd1oc0nw8" //user-generated device id 
  }

Response body example

  {
    "success": true
    "recoveryCode": "qwert12345"   // Random recovery code
  }

Possible Errors

Status Code	Description of possible error
404	Declining recovery request because there are already credentials available for this device

Back to Top

Confirm contacts

Request method and URL

GET /confirm/mobile/:AFiUserId/:confirmationCodeMobile

GET /confirm/email/:AFiUserId/:confirmationCodeEmail

Description

This API is used to confirm a prospect's mobile number or email address. The confirmation code (confirmationCodeMobile or confirmationCodeEmail), which the prospect receives in a text message or email, is given as a path parameter along with the user id (AFiUserId).

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

HTML is returned that will generate a confirmation page with the message, "Email/Mobile confirmed. Thank you" and a link to the Paygears website.

    <!-- html -->
          <h2>Email confirmed</h2> <!-- or "Mobile confirmed" -->
          Thank you.
    <!-- /html -->

Possible Errors

Status Code	Description of possible error
404	Was asked to confirm an email which was already confirmed

Back to Top

Disavow email

Request method and URL

GET /disavow/email/:AFiUserId/:recipientEmailB64

Description

This API is used to disavow or unconfirm an email address. The email address will no longer be honored. However it may be recovered at a later time.

The email address is given as a path parameter, base64 encoded.

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

HTML is returned that will generate a confirmation page with the message, "Email address disavowed. Thank you." and a link to the Paygears website.

    <!-- html -->
          <h2>Email address disavowed</h2> Thank you
          Thank you.
    <!-- /html -->

Back to Top

Harden recovery

Request method and URL

GET /harden/:AFiUserId/:recipientEmailB64

Description

This API is used to disavow an email address and ensure that it cannot be recovered.

The email address is given as a path parameter, base64 encoded.

Request headers

{
    "token": "a long random string" //Authorization token received from /token request
}

Request body None

Response body example

  {
    "Email address disavowed"
        "Thank you."
  }

Back to Top

Generic request

Request method and URL

POST /prospect/generic

Description

This API is used to present an arbitrary request that will be interpreted by the system for a specific user.

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

Response body example

  {
    "success": true
  }

Back to Top

Request websocket

Request method and URL

POST /prospect/connectsocket

Description

Requests authorization of a websocket connection to enable efficient 2-way communication with this prospect.

Required Properties	Description	Schema	Example Values
halfRef	A long random string	string	"z3kygabre2ip1kvxb1p9ty9if7b2ufcpgcjoqk92iqffta5bub6zj5xz54hs0ffi1lzv2zjzikphgqbx"
deviceTag	The device id (provided by user)	string	"o1vd1oc0nw8"

Optional Properties	Description	Schema	Example Values
linkinjected	A link to another user	string, nullable	"null"

Request headers

{
    "Content-Type": "application/json"
    "token": "a long random string" //Authorization token received from /token request
}

Request body example

  {
    "deviceTag": "o1vd1oc0nw8", //user-generated device id 
    "halfRef": "z3kygabre2ip1kvxb1p9ty9if7b2ufcpgcjoqk92iqffta5bub6zj5xz54hs0ffi1lzv2zjzikphgqbx" //a long random string
  }

Response body example

  {
    "success": true
  }

Possible Errors

Status Code	Description of possible error
404	Not enough parameters in the request body, Error recording onboarding socket request

Back to Top