321Forms RESTful Service

RESTful Service for the 321Forms Onboarding Platform

Version 1.9.4

Service Entry Point(s)

PRODUCTION

https://api.321forms.com/v1/

API Return Formats

This service can detect the incoming resource extension in order to provide to you the resource represented according to the extension: 

resource.json

Service Extension Detection: Yes
Allowed Extensions: json
Throw On Invalid Extension: Yes

API Global Headers

Header Type Required Default Description
Authorization string true NSA SHA-1 Encrypted Header (for information on how to create the Authorization Header, scroll to the Creating Acceptable Headers section of the document
Username string true Username of individual responsible for the call.
SentDate string true UTC Timestamp request of when header was created. The call will not be accepted if this timestamp is more than 10 minutes old
Action string true REST action type.

Resource Definitions

The following are all the resources defined in the 321Forms RESTful Service API

company

Returns a list of companies that the user can access

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company.json
Route Pattern has no Placeholders
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
partial string false searchable partial name of the company
offset integer false 0 query search offset
limit integer false 10 (max:50) maximum returned results
Response Default Response Format: json

Samples

The following will be returned when the request was successful.

[
    {
        "name": "Fake Company 1",
        "id": 7
    },
    {
        "name": "Another Fake Company",
        "id": 9
    },
    {
        "name": "Final Fake Company",
        "id": 11
    }
]

company/:companyID/:userType

List array of users in a company {:companyID} based on {:userType} Provided. Will only show users that the requesting account is allowed to manage

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/:userType.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
:userType string true role of users to be searched
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
offset integer false 0 query search offset
limit integer false 10 (max:50) maximum returned results
Response Default Response Format: json

Samples

The following will be returned when {:userType} is employee and the request was successful.

[
    {
        "first_name": "John",
        "role": "employee",
        "id": 1,
        "username": "john",
        "date_created": "March, 05 2013 16:10:19",
        "active": 1,
        "deactive_date": "",
        "last_name": "321forms",
        "email_address": "",
        "division_id": 14
    },
    {
        "first_name": "Ehan",
        "role": "employee",
        "id": 2,
        "username": "ehanjones",
        "date_created": "September, 26 2014 12:09:18",
        "active": 0,
        "deactive_date": "October, 16 2014 00:00:00",
        "last_name": "Jones",
        "email_address": "[email protected]",
        "division_id": 10
    }
]

company/:companyID/complete

Returns a list of 100% onboarded users in the provided company {:companyID}. Sorted by latest approved form date (provided in response as 'utc_latest_approved_date')

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/complete.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
offset integer false 0 query search offset
limit integer false 10 (max:50) maximum returned results
show_uid boolean false false include numeric User ID on return objects
Response Default Response Format: json

Samples

The following will be returned when the company has employees that are 100% complete

[
    {
        "percent_total": 100,
        "progress_towards_completion": 3,
        "username": "myUserName1",
        "approved_forms": 1,
        "total_possible": 3,
        "total_assigned": 1,
        "submitted_forms": 1,
        "household_progress": 1,
        "utc_latest_approved_date": "March, 02 2015 20:03:00",
        "division_id": 2,
        "is_active": 1
    },
    {
        "percent_total": 100,
        "progress_towards_completion": 3,
        "username": "myUserName2",
        "approved_forms": 1,
        "total_possible": 3,
        "total_assigned": 1,
        "submitted_forms": 1,
        "household_progress": 1,
        "utc_latest_approved_date": "March, 01 2015 16:04:00",
        "division_id": 2,
        "is_active": 1
    }
]

company/:companyID/forms

Returns an array of the company's forms. This will be used when selecting the forms to provide for a new hire

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/forms.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

An array of forms and their IDs can be retrieved for a company.

[
    {
        "id": 1,
        "description": "A custom form built specifically for your company",
        "name": "Your Custom Form"
    },
    {
        "id": 2,
        "description": "This is another form that we have custom-built for your company",
        "name": "Another Customer Form"
    }
]

company/:companyID/form/:formID

Returns an array of form questions and an object with the basic details of the form itself

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/form/:formID.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
:formID integer true ID of form of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
type string false questions Type of response to return

Choices:
  • questions : The list of questions that will be asked of the employee
  • pdf : The blank version of the PDF
  • resolution : The list of questions asked of the HR manager when resolving the form
  • signature : The list of questions asked of the employee when signing the form
Response Default Response Format: json

Samples

The following will be returned when a valid company/form ID combo have been processed

{
    "form_questions": [
        {
            "special_format": "",
            "max_value": "",
            "question_type": "textarea",
            "choices": [],
            "question_text": "Last Name (without suffix):",
            "question_number": 0,
            "max_length": 255,
            "min_value": ""
        },
        {
            "special_format": "",
            "max_value": "",
            "question_type": "textarea",
            "choices": [],
            "question_text": "Birth Date:",
            "question_number": 0,
            "max_length": 10,
            "min_value": ""
        },
        {
            "special_format": "",
            "max_value": "",
            "question_type": "radio buttons",
            "choices": [
                true,
                false
            ],
            "question_text": "Have you worked for this company before?",
            "question_number": 0,
            "max_length": "",
            "min_value": ""
        }
    ],
    "form_details": {
        "id": 0,
        "description": "Custom Questionnaire Description",
        "name": "Custom Questionnaire"
    }
}

The following will be returned when param[type] == 'pdf'

{
	"base_64_blank_form":"[URL ENCODED BASE64 DATA]",
	"form_details":{
		"id":0000,
		"description":"Calculates income withheld for federal taxes.",
		"name":"W-4 - 2015"
	}
}

company/:companyID/divisions

Returns a structure containing two elements. the companyID provided and an array of divisions

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/divisions.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

{
    "divisions": [
        {
            "name": "First Division",
            "id": 9
        },
        {
            "name": "Second Division",
            "id": 10
        }
    ],
    "companyID": 1
}

company/:companyID/report

Returns an array of report objects

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/report.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

[
    {
        "name": "Citizenship Status",
        "id": 1
    },
    {
        "name": "Location Information",
        "id": 2
    }
]

company/:companyID/report/:reportID

Returns a structure containing two elements. The first is an array of column headers and the second is the array of user responses with the keys equal to those headers

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/report/:reportID.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
:reportID integer true ID of report of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
startDate date false 1 week from today first date of approval of a form
endDate date false current date last date of approval of a form
complete boolean false false return only 100% complete employees
everify boolean false false return only employees that have e-verify case numbers
eid boolean false false append auto-generated EIDs to the report
includeInactive boolean false false include the inactive employees to the report
divisions int[] false all divisions List of divisions to search
Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

{
    "columns": [
        "Zip_Code",
        "FST",
        "LST",
        "Birth_Date"
    ],
    "results": [
        {
            "Zip_Code": "84351",
            "FST": "Danielle",
            "LST": "Johnson",
            "Birth_Date": ""
        },
        {
            "Zip_Code": "29201",
            "FST": "Angie",
            "LST": "Test",
            "Birth_Date" : ""
        }
    ]
}

company/:companyID/hook

Returns an array of webhooks

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/hook.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

[
    {
        "hash_key": "02c201d1-1286-48b2-bbfb-89f82a42aca0",
        "url": "https://your.secured-url.com",
        "id": "9d0f3821-9dd5-4537-9f41-626c2fda1be4",
        "last_update": "2018-07-24 20:24 +0000",
        "topics": [
            "All Employee Forms Have Been Submitted",
            "An Employee Form Has Been Approved",
            "An Employee Form Has Been Submitted",
            "An Employee Has Reached 100% Onboarded"
        ]
    }
]

company/:companyID/hook

Inserts a new webhook

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/hook.json
Placeholder Type Required Default Description
:companyID integer true ID of company
HTTP Request Methods

Supported: POST
Default: POST

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
url string true Your endpoint that is set up to receive webhooks (must use https)
topics uuid[] true An array of topic IDs that will trigger the new hook
Response Default Response Format: json

Samples

The following is a complete json request to the API.

{
"url" : "https://your.secured-url.com",
	"topics" : [
		"5b6f94eb-0c53-45ef-99ab-a654f5d18223",
		"a9b802e9-998e-4230-9d59-ecdcdb3d3fe1",
		"e8883c8e-06f3-4626-a847-9a0630f90f33",
		"599016c8-f6d0-422b-94c7-a9032bda0c35"
	]

}

The following will be returned when this method is requested successfully.

{
    "hash_key": "02c201d1-1286-48b2-bbfb-89f82a42aca0",
    "url": "https://your.secured-url.com",
    "id": "9d0f3821-9dd5-4537-9f41-626c2fda1be4",
    "last_update": "2018-07-24 20:24 +0000",
    "topics": [
        "5b6f94eb-0c53-45ef-99ab-a654f5d18223",
        "a9b802e9-998e-4230-9d59-ecdcdb3d3fe1",
        "e8883c8e-06f3-4626-a847-9a0630f90f33",
        "599016c8-f6d0-422b-94c7-a9032bda0c35"
    ]
}

company/:companyID/hook/:hookID

Update an existing webhook

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/hook/:hookID.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
:hookID uuid true ID of webhook
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
url string false Your endpoint that is set up to receive webhooks (must use https)
topics uuid[] false An array of topic IDs that will trigger the new hook
Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

{
    "hash_key": "02c201d1-1286-48b2-bbfb-89f82a42aca0",
    "url": "https://your.secured-url.com",
    "id": "9d0f3821-9dd5-4537-9f41-626c2fda1be4",
    "last_update": "2018-07-24 20:24 +0000",
    "topics": [
        "All Employee Forms Have Been Submitted",
        "An Employee Form Has Been Approved",
        "An Employee Form Has Been Submitted",
        "An Employee Has Reached 100% Onboarded"
    ]
}

company/:companyID/hook/:hookID

Returns information about an existing webhook

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/hook/:hookID.json
Placeholder Type Required Default Description
:companyID integer true ID of company
:hookID uuid true ID of webhook
HTTP Request Methods

Supported: PUT
Default: PUT

Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

{
    "hash_key": "02c201d1-1286-48b2-bbfb-89f82a42aca0",
    "url": "https://your.secured-url.com",
    "id": "9d0f3821-9dd5-4537-9f41-626c2fda1be4",
    "last_update": "2018-07-24 20:24 +0000",
    "topics": [
        "All Employee Forms Have Been Submitted",
        "An Employee Form Has Been Approved",
        "An Employee Form Has Been Submitted",
        "An Employee Has Reached 100% Onboarded"
    ]
}

company/:companyID/hook/:hookID

Deletes an existing webhook

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/hook/:hookID.json
Placeholder Type Required Default Description
:companyID integer true ID of company
:hookID uuid true ID of webhook
HTTP Request Methods

Supported: DELETE
Default: DELETE

Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

{
    "success": true
}

company/:companyID/hook/topics

Returns an array of available webhook 'topics'

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/hook/topics.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when this method is requested successfully.

[
    {
        "id": "5b6f94eb-0c53-45ef-99ab-a654f5d18223",
        "simple_key": "all_forms_submitted",
        "description": "All Employee Forms Have Been Submitted"
    },
    {
        "id": "a9b802e9-998e-4230-9d59-ecdcdb3d3fe1",
        "simple_key": "form_approved",
        "description": "An Employee Form Has Been Approved"
    },
    {
        "id": "e8883c8e-06f3-4626-a847-9a0630f90f33",
        "simple_key": "form_submitted",
        "description": "An Employee Form Has Been Submitted"
    },
    {
        "id": "599016c8-f6d0-422b-94c7-a9032bda0c35",
        "simple_key": "onboarding_complete",
        "description": "An Employee Has Reached 100% Onboarded"
    }
]

company/:companyID/plugins

Returns an array of the company's plugins.

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

company/:companyID/plugins.json
Placeholder Type Required Default Description
:companyID integer true ID of company of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

An array of plugins names can be retrieved for a company.

[
    "E-Verify",
    "WOTC - RetroTax"
]

division/:divisionID

Returns basic details for a given division.

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which details will be returned
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
params string false [] comma separated list of additional values to return. Available values are
  • flyers: Flyers that will be presented during the onboarding process
  • uploads: Upload slots that are available for an employee
  • defaults: Forms that are selected as default for new hires
  • everify: E-Verify Client Code and Activation Date
  • wotc: Tax Credit Client and Location IDs
  • contact: division contact details
Response Default Response Format: json

Samples

The following will be returned when all parameters are passed through.

{
    "contact": {
        "fax": "555-555-0000",
        "phone_ext": "7",
        "fax_ext": "",
        "person": "Staff Member",
        "phone": "801-563-5698",
        "email": "[email protected]"
    },
    "formDefaults": [1,2,3,4,5],
    "eVerify": {
        "startDate": "",
        "set": true,
        "clientCompanyId": 0
    },
    "companyID": 0,
    "name": "My Awesome Division",
    "active": true,
    "flyers": [
        {
            "is_active": "yes",
            "name": "Last flyer",
            "id": 0,
            "is_required": "no",
            "description": "some additional details"
        }
    ],
    "employeeUploads": [
        {
            "validTypes": ".txt,.pdf,.ppt,.xls,.doc,.docx,.pptx,.xlsx,.gif,.jpeg,.jpg,.pjpeg,.png",
            "name": "Transcript",
            "id": 0,
            "description": "Some additional details"
        }
    ],
    "taxCredits": {
        "location": "FAKE_LOCATION",
        "client": "FAKE_CLIENT"
    }
}

The following will be returned when no parameters are passed through.

{
    "companyID": 0,
    "name": "My Awesome Division",
    "active": true
}

division/:divisionID/:userType

Returns a list of users for a given division. Response format is the same as 'company/:companyID/:userType'

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID/:userType.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which search is being performed
:userType string true role of users to be searched
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
offset integer false 0 query search offset
limit integer false 10 (max:50) maximum returned results
Response Default Response Format: json

Samples

The following will be returned when {:userType} is employee and the request was successful.

[
    {
        "first_name": "John",
        "role": "employee",
        "id": 1,
        "username": "john",
        "date_created": "March, 05 2013 16:10:19",
        "active": 1,
        "deactive_date": "",
        "last_name": "321forms",
        "email_address": "",
        "division_id": 14
    },
    {
        "first_name": "Ehan",
        "role": "employee",
        "id": 2,
        "username": "ehanjones",
        "date_created": "September, 26 2014 12:09:18",
        "active": 0,
        "deactive_date": "October, 16 2014 00:00:00",
        "last_name": "Jones",
        "email_address": "[email protected]",
        "division_id": 10
    }
]

division/:divisionID/complete

Returns a list of 100% onboarded users in the provided division {:divisionID}. Sorted by latest approved form date (provided in response as 'utc_latest_approved_date')

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID/complete.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
offset integer false 0 query search offset
limit integer false 10 (max:50) maximum returned results
show_uid boolean false false include numeric User ID on return objects
Response Default Response Format: json

Samples

The following will be returned when the division has employees that are 100% complete

[
    {
        "percent_total": 100,
        "progress_towards_completion": 3,
        "username": "myUserName1",
        "approved_forms": 1,
        "total_possible": 3,
        "total_assigned": 1,
        "submitted_forms": 1,
        "household_progress": 1,
        "utc_latest_approved_date": "March, 02 2015 20:03:00",
        "division_id": 2,
        "is_active": 1
    },
    {
        "percent_total": 100,
        "progress_towards_completion": 3,
        "username": "myUserName2",
        "approved_forms": 1,
        "total_possible": 3,
        "total_assigned": 1,
        "submitted_forms": 1,
        "household_progress": 1,
        "utc_latest_approved_date": "March, 01 2015 16:04:00",
        "division_id": 2,
        "is_active": 1
    }
]

division/:divisionID/flyers

Returns an array of the division's flyers

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID/flyers.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

An array of flyers and their IDs can be retrieved for a division.

[
    {
        "name": "Flyer 1",
        "id": 1,
        "description": "A very helpful description"
    },
    {
        "name": "Flyer 2",
        "id": 2,
        "description": "Another helpful description"
    }
]

division/:divisionID/flyers/:flyerID

Returns an array of the division's flyers

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID/flyers/:flyerID.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which search is being performed
:flyerID integer true ID of flyer to download
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

An object of flyer data.

{
	"data":"[URL ENCODED BASE64 DATA]",
	"file":"MyExampleFlyer.pdf",
	"uploaded":"December, 14 2017 18:30:00 -0600",
	"extension":"application/pdf"
}

division/:divisionID/forms

Returns an array of the company's forms, with the additional information on which forms are 'selected_as_default' for a division. This will be used when selecting the forms to provide for a new hire. An employee that is to be placed within a certain division should have the defaults selected if provided

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID/forms.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

An array of forms and their IDs can be retrieved for a company.

[
    {
        "id": 1,
        "name": "Your Custom Form",
        "description": "A custom form built specifically for your company",
        "selected_as_default": true
    },
    {
        "id": 2,
        "name": "Another Customer Form",
        "description": "This is another form that we have custom-built for your company",
        "selected_as_default": false
    }
]

division/:divisionID/prefill

Returns an array of questions that will be asked of an employee during account creation. These values are used for data that is variable for each employee, but needs to be entered prior to an employee signing their documents

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

division/:divisionID/prefill.json
Placeholder Type Required Default Description
:divisionID integer true ID of division of which search is being performed
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

An array of questions that will be asked of an employee during account creation.

[
    {
        "max_length": "",
        "question_number": 1,
        "required" : true,
        "question_type": "textarea",
        "special_format": "",
        "question_text": "Company Code:",
        "choices": [],
        "max_value": "",
        "prepopulated_value": "XX7777",
        "min_value": "",
        "forms" : [],
        "help_text" : "Consult your HR Handbook for more information", 
        "note_text" : "", 
        "example_text" : "780"
    },
    {
        "max_length": "",
        "question_number": 2,
        "required" : false,
        "question_type": "textarea",
        "special_format": "",
        "question_text": "Today's Date:",
        "choices": [],
        "max_value": "",
        "prepopulated_value": "",
        "min_value": "",
        "forms" : [1,2,3],
        "help_text" : "", 
        "note_text" : "", 
        "example_text" : "1/1/2018"
    }
]

users/find-username/:userID-numeric

Returns an individual username and active status based on known numeric user id.

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/find-username/:userID-numeric.json
Placeholder Type Required Default Description
:userID-numeric string true numeric User ID assigned to user upon creation. This is not the username that is also referred to as userID througout the API doc
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when the request was successful for a user you can manage.

{
    active: true,
    username: "testingemployee"
}

users/:userID

Returns an individual user based on {:userID}.

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID.json
Placeholder Type Required Default Description
:userID string true username of employee being searched
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when the request was successful for a user you can manage.

{
    "first_name": "Testing",
    "id": 11,
    "username": "testingemployee",
    "active": true,
    "email_address": "[email protected]",
    "last_name": "Employee",
    "roles": {
        "employee": [
            {
                "divisionID": 1,
                "companyID": 1
            }
        ],
        "staff": [
            {
                "divisionID": 2,
                "companyID": 1
            }
        ]
    }
}

The following will be returned when the request was successful for your own account. In this case, the agency_id and site_id values refer to companyID and divisionID, respectively

{
    "roles": {
        "admin": [
            {
                "SITE_ID": "",
                "AGENCY_ID": ""
            }
        ],
        "reseller": [
            {
                "SITE_ID": "",
                "AGENCY_ID": 1
            }
        ],
        "hrAdmin": [
            {
                "SITE_ID": "",
                "AGENCY_ID": 2
            }
        ],
        "staff": [
            {
                "SITE_ID": 10,
                "AGENCY_ID": 3
            }
        ]
    },
    "first_name": "Testing",
    "id": 11,
    "username": "testinguser",
    "active": true,
    "email_address": "[email protected]",
    "last_name": "Employee"
}

users/:userID

Creates a new employee based on :userID

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID.json
Placeholder Type Required Default Description
:userID string true username of employee being created
HTTP Request Methods

Supported: POST
Default: POST

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
firstName string true First name of New Employee
lastName string true Last name of New Employee
companyId integer true Company to place New Employee
emailAddress string false email address of employee being created
note: this field its required if the newUI param its true and must match the :userID
sendActivationEmail boolean false Determine if you want an activation email to be automatically sent to the new employee. emailAddress field must be present for activation email to be sent
sendSMS string false Determine if you want an activation SMS sent. When true and accompanied with a valid "phoneNumber" parameter, this will supercede "sendActivationEmail" choice.
password string false password of employee being created. If not provided, we will generate one for you
phoneNumber string false SMS-enabled phone number to receive activation SMS. Must be a 12-character, US-based phone number including country code (e.g.: +15551231234). Only used when "sendSMS" is true.
divisionId integer true Division to place New Employee
newUI boolean false Determines if the new Canary onboarding UI should be used
job_title string false Job title of New Employee
note: this field its required if the newUI param its true
forms int[] true List of forms to provide to New Employee
isTest boolean false false if true, will not actually save the employee. Useful for testing structure of your JSON
responses object[] false Object of responses. Each object consists of {id:int} and {response:string} of question you will pre-populate for your new hire
responseValidation string false ignore A flag to indicate what to do when a response provided in the responses array is invalid.

Valid options:
  • error : When a data validation occurs, user creation is stopped and an array is returned displaying the invalid responses. Will return a response code of 422 indicating the bad data.
  • warn : When a data validation occurs, user creation continues, but a warning message is returned indicating the responses that could not be saved due to invalid data.
  • ignore : Process the reponses regardless of data validation errors. Data will be handled upstream in the normal form process where applicable.This is the default option for API version 1, but will be deprecated in upcoming releases.
Response Default Response Format: json

Samples

The following is a complete json request to the API.

{
	"companyID" : 1,
	"divisionID" : 5,
	"firstName" : "Jon",
	"lastName" : "Doe",
	"emailAddress" : "[email protected]",
	"forms" : [1,2,3,"D"],
	"responses" : 
		[
			{
				"id" : 1,
				"response" : "First Front-End Response"
			},
			{
				"id" : 2,
				"response" : "Yes"
			}
		],
	"isTest" : true
}

The following will be returned when the request was successful.

{
    "SUCCESS": true,
    "USER_ID": 0,
    "DETAIL": "Onboard Success",
    "SSO_EMPLOYEE_ID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "ALL_RESPONSES_SAVED": true,
    "USERNAME": "321Test",
    "PASSWORD": "ARealPasswordWillBeHere"
}

The following will be returned when the request was successful, but an invalid response was provided and responseValidation has been set to 'warn'.

{
    "SUCCESS": true,
    "USER_ID": 0,
    "DETAIL": "Onboard Success",
    "SSO_EMPLOYEE_ID": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
    "ALL_RESPONSES_SAVED": true,
    "USERNAME": "321Test",
    "PASSWORD": "ARealPasswordWillBeHere",
    "WARNINGS": {
        "INVALID_RESPONSES": [
            {
                "response": "agdgdg",
                "error": "The response provided is not a valid Social Security Number",
                "question_no": 51
            }
        ]
    }
}

The following will be returned when an error occurred.

{
    "SUCCESS": false,
    "USER_ID": 0,
    "DETAIL": "The username provided is unavailable. Please enter another username.",
    "SSO_EMPLOYEE_ID": null,
    "ALL_RESPONSES_SAVED": null,
    "USERNAME": "321Test",
    "PASSWORD": null
}

users/:userID

Updates an existing employee based on :userID

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID.json
Placeholder Type Required Default Description
:userID string false username of employee being updated
HTTP Request Methods

Supported: PUT
Default: PUT

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
firstName string false First name of existing Employee
lastName string false Last name of existing Employee
emailAddress string false email address of existing employee
username string false new username of existing employee
password string false new password of existing employee
active boolean false activates/deactivates existing employee
Response Default Response Format: json

Samples

The following will be returned when the request was successful for a user you can manage. It is the same response as the 'GET' method of the same name

{
    "first_name": "Testing",
    "id": 11,
    "username": "testingemployee",
    "active": true,
    "email_address": "[email protected]",
    "last_name": "Employee",
    "roles": {
        "employee": [
            {
                "divisionID": 1,
                "companyID": 1
            }
        ],
        "staff": [
            {
                "divisionID": 2,
                "companyID": 1
            }
        ]
    }
}

users/:userID/available

Tests if a username is available for use in a new account

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/available.json
Placeholder Type Required Default Description
:userID string true username being checked for availability
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when the request was successful.

{
    "success": true,
    "detail": "Username jengland355235 is currently available"
}

The following will be returned when an error occurred.

{
    "success": false,
    "detail": "(fakename): The username provided is unavailable. Please enter another username."
}

users/:userID/everify

Returns the lastest E-Verify case information about an employee

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/everify.json
Placeholder Type Required Default Description
:userID string true username of the employee
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when the request was successful. Status text may vary based on values transmitted by E-Verify's web service and should not be relied on for logic determination

{
    "casenumber": "2016124....XXXX",
    "status": "Case Closed",
    "authorized": true
}

users/:userID/forms

List the forms available to an employee and the UTC Timestamps of the latest submitted and approved versions

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/forms.json
Placeholder Type Required Default Description
:userID string true username of person whose questions are being selected
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
includeAll boolean false false Do you want to include all of the forms this user submitted but are no longer assigned to them. Choices: true/false
includeInactive boolean false false Do you want to include all of the forms this user submitted but are no longer active within your company. Choices: true/false
Response Default Response Format: json

Samples

The following will be returned when a request is successful and the employee has at least one form

[
    {
        "utc_latest_submission_date": "November, 20 2015 17:23:30",
        "form_id": 1,
        "utc_latest_approved_date": "October, 09 2015 17:17:48"
    },
    {
        "utc_latest_submission_date": "November, 12 2015 21:54:15",
        "form_id": 22,
        "utc_latest_approved_date": "July, 22 2015 18:41:31"
    },
    {
        "utc_latest_submission_date": "November, 12 2015 21:54:01",
        "form_id": 33,
        "utc_latest_approved_date": "November, 12 2015 22:17:16"
    },
    {
        "utc_latest_submission_date": "October, 22 2015 19:13:43",
        "form_id": 44,
        "utc_latest_approved_date": ""
    },
    {
        "utc_latest_submission_date": "October, 22 2015 22:13:47",
        "form_id": 99,
        "utc_latest_approved_date": ""
    }
]

users/:userID/form/:formID

Complex

Receives response information of a user's latest form of a particular status

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/form/:formID.json
Placeholder Type Required Default Description
:userID string true username of person whose form is being selected
:formID string true form id of document to return
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
type string false questions Type of response to return. Choices: questions,fields,pdf,url
status string false approved Status document needs to be in for return. Choices: approved,submitted
Response Default Response Format: json

Samples

The following will be returned when param[type] == 'questions'.

{
    "formID": 0000,
    "formInfo": {
        "utc_submission_timestamp": "July, 20 2014 23:08:32",
        "approved": true,
        "utc_approved_timestamp": "July, 20 2014 23:08:32",
        "aaid": 0000000
    },
    "questions": [
        {
            "response": "Doe",
            "question_number": 21
        },
        {
            "response": "John",
            "question_number": 204
        },
        {
            "response": "L",
            "question_number": 59
        }
    ],
    "userID": "FAKE_USERNAME"
}

The following will be returned when param[type] == 'fields'.

{
    "formID": 0000,
    "formInfo": {
        "utc_submission_timestamp": "July, 20 2014 23:08:32",
        "approved": true,
        "utc_approved_timestamp": "July, 20 2014 23:08:32",
        "aaid": 000000
    },
    "fields": [
        {
            "name": "eSignature_eSignature_1",
            "value": "John Doe"
        },
        {
            "name": "office_name",
            "value": "Test Division"
        },
        {
            "name": "Primary_full_name_1",
            "value": "John Doe"
        },
        {
            "name": "submission_date",
            "value": "07/20/2014"
        },
        {
            "name": "submission_date_yf",
            "value": "2014/07/20"
        },
        {
            "name": "submission_day",
            "value": 20
        },
        {
            "name": "submission_month",
            "value": "July"
        },
        {
            "name": "submission_time",
            "value": "4:08:32 PM PDT"
        },
        {
            "name": "submission_year",
            "value": 2014
        }
    ],
    "userID": "FAKE_USERNAME"
}

The following will be returned when param[type] == 'pdf'.

{
    "formID": 0000,
    "pdf": {
        "data": "[URL ENCODED BASE64 DATA]",
        "info": "base64 representation of binary object"
    },
    "formInfo": {
        "utc_submission_timestamp": "July, 20 2014 23:08:32",
        "approved": true,
        "utc_approved_timestamp": "July, 20 2014 23:08:32",
        "aaid": 000000
    },
    "userID": "FAKE_USERNAME"
}

The following will be returned when param[type] == 'url'.

{
    "formID": 0000,
    "url": {
        "data": "https://..",
        "info": "A temporary URL for your PDF. This link will expire"
    },
    "formInfo": {
        "utc_submission_timestamp": "July, 20 2014 23:08:32",
        "approved": true,
        "utc_approved_timestamp": "July, 20 2014 23:08:32",
        "aaid": 000000
    },
    "userID": "FAKE_USERNAME"
}

users/:userID/responses

Receives response information to questions asked of a user

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/responses.json
Placeholder Type Required Default Description
:userID string true username of person whose questions are being selected
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
questions int[] false all questions List of questions to return responses
offset integer false 0 query search offset
limit integer false 100 (max:500) maximum returned results
Response Default Response Format: json

Samples

The following will be returned when a request is successful.

Two important distinctions within the response are:

  1. Responses are represented in an array in case of multi-select options, and
  2. All responses will have leading and trailing spaces to ensure that response data is not mis-cast (for example: SSN 000000007 may be cast as 7 if not for spaces)

[
    {
        "responses": [
            " Male "
        ],
        "question_text": "Gender:",
        "question_number": 23
    },
    {
        "responses": [
            " 01/02/1990 "
        ],
        "question_text": "Birth Date:",
        "question_number": 22
    },
    {
        "responses": [
            " Jones "
        ],
        "question_text": "Last Name (without suffix):",
        "question_number": 21
    }
]

users/:userID/basicInformation

Receives basic user information for an employee's account

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/basicInformation.json
Placeholder Type Required Default Description
:userID string true username of person whose questions are being selected
HTTP Request Methods

Supported: GET
Default: GET

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
fw boolean false false Include Federal Withholding Information
sw boolean false false Include State Withholding Information
Response Default Response Format: json

Samples

The following will be returned when a request is successful.

{
    "basic": {
        "emailAddress": "[email protected]",
        "lastName": "Bach",
        "zipCode": "11111",
        "homePhone": "800-555-1212",
        "gender": "",
        "birthDate": "01/27/1990",
        "state": "NY",
        "firstName": "Johann",
        "streetAddress": "123 fake street",
        "middleInitial": "",
        "city": "new york"
    }
}

users/:userID/uploads

List the uploaded documents associated with the employee's account

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/uploads.json
Placeholder Type Required Default Description
:userID string true username of person whose questions are being selected
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when a request is successful and the employee has at least one uploaded document

[
    {
        "utc_upload_timestamp": "September, 25 2015 19:37:21 +0000",
        "category": "logos",
        "id": 0000000,
        "name": "321formslogo_final.jpg",
        "description": "321Forms Logo"
    }
]

users/:userID/uploads/:fileID

Grabs an individual uploaded document

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

users/:userID/uploads/:fileID.json
Placeholder Type Required Default Description
:userID string true username of person whose questions are being selected
:fileID numeric true ID of particular document to grab. Form IDs can be found using the 'users/:userID/uploads' endpoint
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

The following will be returned when a request is successful

{
    "data": "[URL ENCODED BASE64 DATA]",
    "utc_upload_timestamp": "September, 25 2015 19:37:21 +0000",
    "category": "logos",
    "name": "321formslogo_final.jpg",
    "extension": "image/jpeg",
    "description": "321Forms Logo"
}

SSO/generate

Returns a simple object with the variable 'SSOKey' that can be used to initiate a single sign-on account for a user

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

SSO/generate.json
Route Pattern has no Placeholders
HTTP Request Methods

Supported: GET
Default: GET

Response Default Response Format: json

Samples

{
    "SSOKey": "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX"
}

SSO/:EmployeeCFUUID

Returns an object that includes the endpoint to contiune with the SSO process. You must register your application as an SSO Provider with 321Forms prior to utilizing this endpoint

URL Pattern Placeholders

The following patterns are part of the RESTful resource and must be passed in the exact position shown in the URL resource. Usually placeholders start with a (:) colon.

SSO/:EmployeeCFUUID.json
Placeholder Type Required Default Description
:EmployeeCFUUID CFUUID true Unique Identifier for a user account. Can be generated using the 'SSO/generate' endpoint
HTTP Request Methods

Supported: POST
Default: POST

HTTP Parameters

HTTP Parameters are passed to the resource via the URL or via FORM posts depending on the HTTP verb used.

Header Type Required Default Description
redirect object false {} an object that describes where to redirect the user to once single sign-on has been completed
redirect.action string true for all redirect requests redirect destination.

Current options:
  • employee-folder : Redirects to an employee's folder. corresponding id parameter will be the employee's unique numeric ID
  • division : Redirects to a division home page. Corresponding id refers to the division's unique numeric ID
redirect.id numeric true for all redirect requests id of redirect destination
Response Default Response Format: json

Samples

To Redirect to a specific destination, post an object into the payload such as this

{
	"redirect":{
		"action":"employee-folder",
		"id":XXXXX
	}
}

The following response indicates that the user needs to grant access to your application to connect via SSO with the 321Forms system. The endpoint returned will be placed on the end of the 321Forms url or your preferred white label version of 321Forms (Ex: https://my.321Forms.com/content/login/grant_access.cfm?key=XXXXXXXXX). The 'confirmed' element allows you to see if the user has already confirmed SSO. A 'confirmed' value of false indicates that this is a new connection

{
    "endpoint": "/content/login/grant_access.cfm?key=XXXXXXXXX",
    "confirmed": false
}

HTTP Response Codes

All RESTful service APIs should return appropriate HTTP Status Codes for every request.

Code Description
200 Success!
201 Created. A new resource has been created successfully. The response body is either empty or contains a representation revealing the URI of the newly created resource.
202 Accepted. The request was valid and accepted but not yet processed. The response body should containe a URI to poll for status updates or a token assigned to this request. This allows for asynchronous REST requests.
204 No content. The request was successfull but the server has no response for it.
301 Moved permanently
302 Moved temporarily. The requested resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client SHOULD continue to use the Request-URI for future requests
400 Bad request. Look at the accompanying error messages to see why the request was invalid.
401 Unauthorized. Client not authorized to make the request.
403 Forbidden. The request is understood, but it has been refused. Look at the accompanying error messages to see why the request was invalid.
404 Not Found
405 Method Not Allowed. The requested method is not allowed for that resource
406 Not Acceptable. Cannot generate representation with given formats, headers or parameters.
410 Gone, the resource is no longer available.
429 Too Many Requests.
500 Internal service error.
503 Service unavailable. Maybe too many requests.

Creating Acceptable Headers

RESTful transactions are used because they are EASY!!, however we still need them to be secured. Because of that all requests made to our RESTful API must include the proper headers in order to proceed with a transaction

What you need to know:
Item Description
321Forms Username The username attached to your 321Forms account
SSO Secret Key AN SSO Secret Key can be generated by 321Forms by visiting the Edit Account page when logged into 321Forms. Only one secret can be generated at a time, so if you misplace your secret or believe it has been compromised, a new one can be generated in its place. NOTE: if you are a partner who already generates SSO keys for your users, the keys you generate can be used here as well.

Once you have your SSO Secret Key, you are ready to start making calls to the web service. Each RESTful call requires four headers to be attached. For more information on the required headers, scroll to the API Global Headers section of this documentation. Of these headers, the Authorization header requires some work that will be detailed in the next section

The Authorization Header

The authorization header is built to ensure that malicious calls cannot be created by a third party on your behalf. The simple description is already listed in the API Global Headers section, however this section will step your through the encryption process

Step 1. Creating your JSON object

The json object contains three values that are exactly the same as your headers of the same name (Username, SentDate, Action). It is important to create this JSON exactly the same way it is represented on this page, as your requests will fail if the format varies.

Here is an example of the structure, assuming the username sample_user:

{"Username":"sample_user","SentDate":"{ts '2014-10-20 19:32:48'}","Action":"GET"}

Step 2. Creating the SHA-1 hash

  • An SHA-1 hash can be built using any programming language. If you are unfamiliar with this cryptographic hash function, here's the Wikipedia page explaining it in detail.
  • If you would like to test your hash function, one website that will allow you to hash a string with a key of your choice is Online Converter.
  • Your final hash key should be converted into base64
Using the JSON string provided above and an encryption key of 1234567890, your base64 representation of the hash will be C+ofkWM27JCzdkZKUndMEhOjA9o=. This result will be your Authorization header.

Full API Client Implementation
.Net
GitHub User and 321Forms partner pdsteward has shared his implementation of 321Forms integration, which can be viewed here.

Clone from GitHub using the following command:

	git clone https://github.com/pdstewart/Dss.OnboardingApiClient.git
Node.js
If you'd like to connect to the API via Node.js, please see the official 321Forms Node.js API connection implementation here.

Clone from GitHub using the following command:

	git clone https://github.com/JEinOKC/321Forms-NodeJS.git
Code Examples
C# 

/*
    The following was provided by an integration partner who was kind enough to share with us his code.  
*/

using System;
using System.Security.Cryptography;
// Source: http://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

namespace Program
{
    class Program
    {
        static string GetHMACSHA1Hash(string TextToHash, string EncryptionKey)
        {
            var encoding = new System.Text.ASCIIEncoding();
            byte[] keyBytes = encoding.GetBytes(EncryptionKey);
            byte[] textBytes = encoding.GetBytes(TextToHash);
            using (var hasher = new HMACSHA1(keyBytes))
            {
                byte[] hashBytes = hasher.ComputeHash(textBytes);
                return Convert.ToBase64String(hashBytes);
            }
        }
        static void Main()
        {
            string Username = "sample_user";
            string SentDate = "2014-10-20 19:32:48"; //DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
            string Action = "GET";
            string json = string.Format("{{\"Username\":\"{0}\",\"SentDate\":\"{{ts '{1}'}}\",\"Action\":\"{2}\"}}", Username, SentDate, Action);
            string key = "1234567890";
            string Authorization = GetHMACSHA1Hash(json, key);
            
            Console.SetWindowSize(90, 10);
            Console.WriteLine(json);
            Console.WriteLine(Authorization);
            Console.ReadLine();
        }
    }
}
Step 3. Sending the request with headers

At this point, you have your 4 header values and the request should be able to be processed. Good Luck!

Changelog

1.9.4

  • added boolean includeInactive option for users/:userID/forms endpoint
  • added new endpoint "users/find-username/:userID-numeric" to allow you to find a username based off of the sytem-assigned user id

1.9.3

  • added boolean includeInactive option for company/:companyID/report/:reportID endpoint

1.9.2

  • added boolean includeAll option for :userID/forms.json endpoint

1.9.1

  • Added 'signature' as option for the parameter 'type' in :apiversion/company/:companyID/form/:formID endpoint

1.9.0

  • Added the optional 'useSMS' and 'phoneNumber' parameters to the users/:userID (post) endpoint

1.8.0

  • Added company/:companyID/plugins endpoint

1.7.1 - 1.7.4

  • Minor patches and internal updates

1.7.0

  • Added the optional 'responseValidation' parameter to the users/:userID (post) endpoint

1.6.9

  • Added everify and eid options for company/:companyID/report/:reportID endpoint

1.6.8

  • Added optional password parameter for user creation

1.6.7

  • Added users/:userID/basicInformation endpoint
  • Added webhook endpoints

1.6.6

  • Added division/:divisionID/flyers endpoint
  • Added division/:divisionID/flyers/:flyerID endpoint

1.6.5

  • added the following fields in prefill endpoint response object: forms, help_text, note_text, example_text

1.6.4

  • Added redirection capabilities for Single Sign-On

1.6.3

  • Added "required" boolean in response for division/:divisionID/prefill endpoint

1.6.2

  • Added division/:divisionID/prefill endpoint

1.6.1

  • Added users/:userID/everify endpoint

1.6.0

  • Added 'url' as valid type in users/:userID/form/:formID.json endpoint. This will return a temporary URL to a form as an alternative to returning the data
  • Updated division/:divisionID/forms.json endpoint to remove any forms that are considered 'private' within the company and have not been specifically assigned to that division
  • Added constraint that blocks deactivated companies from using the user creation process

1.5.1

  • Updated staff access to division/:divisionID/:userType when userType is 'employee'

1.5.0

  • Added 'resolution' as option for the parameter 'type' in :apiversion/company/:companyID/form/:formID endpoint

1.4.0

  • Added 'PUT' method for user/:userID endpoint
  • Added 2 Single Sign-on Endpoints: SSO/generate & SSO/:EmployeeCFUUID

1.3.1

  • Added 'roles' object to return value for users/:userID endpoint. All visible roles displayed will be roles beneath the user performing the query. Roles outside of this scope will be hidden from view

1.3.0

  • Added 2 new endpoint: company/:companyID/report & company/:companyID/report/:reportID

1.2.0

  • Added 1 new endpoint: users/:userID/forms

1.1.0

  • Added optional 'show_uid' parameter on company/complete and division/complete endpints
  • Added 2 new endpoints: users/:userID/uploads and users/:userID/uploads/:fileID

1.0.2

  • Updated security constraints to allow HR Staff to use select segments of the API

1.0.1

  • Fixed check on company/division combo. When user had access to both, but division was not in company, employee creation was still attempted

Receive Updates For This API

* indicates required
COMPLEX requests are those requests that take up a larger portion of computation time on the API. Requests labeled as 'complex' may not be sent at a frequency higher than 1 request per account per second.