Verification API

What can you do with the API?

The GovX Verification API is designed to allow you to create and edit campaigns under your listing. Campaigns can be used to create multiple unique experiences under a single parent listing. For example, if you are a registration or ticketing platform, you can use campaigns to create custom verification experiences for clients using your platform. You can read more about campaigns here.

Specifically, the API allows you to:

Retrieve data for a campaign under your listing
Create a campaign under your listing
Edit a campaign under your listing

You can set and edit the following campaign elements:

Campaign name
Logo, including image, height and alignment. This logo is shown in the registration flow (see Bauwow Pet Supplies logo at the right). See specs
Welcome message shown on landing page (see "Bauwow has partners..." at the right) See specs
Eligible occupations. See specs

Security and Authorization

All requests are authorized using a bearer token. Unauthorized requests will receive an Unauthorized or Forbidden response code.

Issuing a new Bearer Token

Use the following steps to issue a new bearer token. Note that when issuing a bearer token, all pre-existing tokens will be invalidated. Bearer tokens should be kept secret, GovX does not have a way to re-issue a pre-existing token as these are signed using a one-way hash and the tokens themselves are not stored by GovX.

Login to https://partners.govx.com
Go to your listing settings
Navigate to the "Deploy" tab.
Select "Credentials" on the left navigation.
Click "Create New Bearer" under "Bearer Token"
This will display a pop-up modal with instructions for creating the token. Click "Create" and then copy the newly generated token.

Using the token in API requests.

Pass your bearer token using request header:

Authorization: Bearer {token}

GET Campaign

Retrieves a specific campaign.

GET /api/auth/campaigns/:id

Field	Description
id	The ID of the campaign

Sample response:

HTTP/1.1 200 OK 
  
  { 
  	"id": 1001, 
    "listingId": 101, 
    "name": "My Campaign", 
    "ui": { 
    	"template": { 
      	"header": { 
        	"logoHeight": 90, 
          "logoAlignment": "center", 
          "logoImage": { 
          	"url": "https://www.govx.com/{PATH}" 
          }, 
          "logoOrientation": "portrait" 
        } 
      }, 
      "messaging": { 
      	"welcomeMessage": "My Welcome Message" 
      } 
    }, 
    "occupationGroups": [ 
    		{ 
      		"key": "military", 
        	"showInRegistration": true 
      	}, 
      	{ 
      		"key": "first-responders", 
        	"showInRegistration": false 
      	} 
      ], 
      "occupations": [ 
      	{ 
        	"occupationId": 2, 
          "showInRegistration": true 
        },
  			{ 
        	"occupationId": 201, 
          "showInRegistration": true 
        } 
      ]
   }

POST Campaign

Creates a new campaign.


POST api/auth/campaigns 
Content-Type: application/json 

{ 
	"name": "My Campaign", 
  "ui": { 
  	"template": { 
    	"header": { 
      	"logoHeight": 90, 
        "logoAlignment": "center", 
        "logoImage": { 
        	"encoded": "data:{MIME_TYPE};base64,{BASE64}" 
        }, 
        "logoOrientation": "portrait" 
      } 
    },
    "messaging": { 
    	"welcomeMessage": "My Welcome Message" 
    } 
  }, 
  "occupationGroups": [ 
  	{ 
      "key": "military", 
      "showInRegistration": true 
    }, 
    { 
    	"key": "first-responders",
      "showInRegistration": false 
    } 
  ]
}

Field	Type	Description
campaign	Campaign	The body should contain a campaign object.

PUT Campaign

Updates a campaign, when passing fields for an update, you only need to pass in the fields that you want updated, the system will mantain previous settings and only override the passed in fields.

PUT /api/auth/campaigns/:id

Field	Type	Description
campaign	Campaign	The body should contain a campaign object with the id defined.

Example:

  
PUT api/auth/campaigns/22 
Content-Type: application/json 

{ 
	"id": 22, 
  "name": "My Campaign", 
  "ui": { 
  	"messaging": { 
    	"welcomeMessage": "My Welcome Message" 
    }
  }, 
  "occupationGroups": [ 
  	{ 
    	"key": "military", 
      "showInRegistration": true 
    }, 
    { 
    	"key": "first-responders", 
      "showInRegistration": false 
    } 
  ] 
}

Response Status Codes

The following table contains common response codes from our system.

Status	Code	Description
200	OK	The request was successful. This will typically contain a response body.
201	Created	Used for POST. Contains the URI of the campaign in the header.
400	Bad Request	An error occurred. When possible, the response will contain a list of error messages.
401	Unauthorized	The request was not authorized.
403	Forbidden	You do not have access to the resource.
404	Not Found	The resource could not be found.

Types

Campaign

The campaign model acts as a container for all campaign information, this is returned in GET requests.

Field	Type	Description
ID	int	A unique ID for a campaign. This is used in both GET and PUT requests for targetting a specific campaign.
ListingId	int	The listing ID that owns the campaign. You will only have access to campaigns identified by your listing.
Name	string	The name of the campaign. Using unique campaign names can help identify the campaign.
ui	UI	Encapsulates the UI settings for the campaign.
occupationGroups	OccupationGroup[]	An array of occupation groups that determines which occupations are available for this campaign.
occupations	Occupation[]	An array of occupations that determine which occupations are available for this campaign.

A note on occupations and occupations groups: Only one of the two should be used with a single campaign. Occupation groups are used to target a pre-determined list of occupations on GovX. This makes it easier to manage which occupations are allowed, and the occupations in the groups are maintained by GovX. If you want more granular control of permissions, then use occupations.

Header

Manages different aspects of the header in the front-end UI.

Field	Type	Description
logoHeight	int	Sets the height (px) allocated for the header logo. This should range between 30 and 150 px for optimal display.
logoAlignment	string	Aligns the logo in the header (left, center, right).
logoImageUrl	string	The path to the image once uploaded to GovX servers.
logoImage	Image	Used to set the image in the header.
logoOrientation	string	Defines the orientation of the logo image (portrait, landscape). This will automatically be detected based on the uploaded image.

Image

The image model is used for uploading an image for a campaign and also for displaying details about the image. The API supports multiple image types as defined below.

Base64 Encoded Image

The Base64 encoded image is used for uploading images using a single encoded string in the format: "data:{MIME_TYPE};base64,{BASE64}"

Field	Type	Description
encoded	string	Base64 string for image using a data URL format.

Base64 Image

The Base64 image allows uploading an image using the fields split out.

Field	Type	Description
base64Data	string	The image data base64 encoded.
mimeType	string	Mime-type for the given image.

URL Image

The URL image is used in responses only. This will contain the URI where the image is hosted on GovX.

Field	Type	Description
url	string	URI of the image resource.

Messaging

Manages the messages seen by the customer when authorizing on the front-end.

Field	Type	Description
welcomeMessage	string	Text that will be displayed on the registration landing page for end-users. Max 200 characters including spaces.

Occupation

Allows granular selection of occupations that should be eligible for verification. To see the full list of occupations supported by GovX, please reference this list.

Field	Type	Description
occupationId	int	ID of occupation.
showInRegistration	bool	If false, the occupation will pass verification but not be displayed in the UI. If true, the occupation will be displayed as an eligible option in the UI.

Occupation Group

An occupation group represents a list of occupations that are managed by GovX. Using occupation groups in your campaigns simplifies your set up. Simply target at the group level (i.e. Military) and let GovX manage the settings of all child occupations under the group (i.e. Military/Army/Veteran, etc). Using occupation groups ensures your campaigns are always up-to-date with our latest occupation taxonomy.

Field	Type	Description
key	string	The key of the occupation group. See below for full list.
showInRegistration	bool	Always pass true for this field. This feature will be deprecated in an upcoming release.

Occupation Group Keys

Key	Description
military	Military members (Air Force, Air National Guard, Army, Army National Guard, Coast Guard, Marines, Navy)
military-family	Family members of military members, including spouses and dependents.
other-govt	Includes government employees and their family members.
teacher	Teachers and staff (K-12 and University)
law-enforcement	Federal, state and local law enforcement officials
medical	EMTs, nurses and hospital physicians
fire	Full-time and volunteer fire fighters
first-responders	Includes Law Enforcement, Medical and Fire.

Template

Manages different areas and components on the front-end UI.

Field	Type	Description
header	Header	UI header settings.

UI

The UI model contains different settings for controlling what the end-user will see on the front-end.

Field	Type	Description
template	Template	Controls the display settings for the UI.
messaging	Messaging	Controls messages for the UI.