RetroTax

Getting Started

Documentation Overview

This API allows RetroTax partners to seamlessly integrate WOTC screening, in addition to geographic and state-level tax credits, into their existing software platforms so that RetroTax can handle the back-end logic to screen and process candidates.

Intended Audience

This API documentation is intended for software developers of Human Resource Information Systems (HRIS) who aim to integrate tax credit screening into their platforms.

WOTC Overview

The Work Opportunity Tax Credit (WOTC) program is an incentive program that provides businesses with a federal income tax credit to hire individuals from targeted groups that have a particularly high unemployment rate or other special employment needs. The WOTC credit is calculated on “qualified first-year wages” and has a maximum credit of $2,400, $4,800, $5,600 or $9,600 per eligible employee, depending upon the employee’s eligible Target Group. For more detailed information, read IRS Publication 954

WOTC FAQs

For general non-API related background information and FAQs visit https://www.retrotax-aci.com and our WOTC FAQs

Integration Overview

This documentation set is geared toward full API integrations. RetroTax offers alternative integrations with varying trade-offs. For a quicker integration, we recommend the RetroTax Plugin. Please email tech@retrotax-aci.com. A preliminary discussion can determine the best direction give your company's requirements.

Service Entry Points:

We facilitate two types of end-points in three different environments:

Production

  1. SNI-enabled - https://api.retrotax-aci.com
  2. SNI-disabled - https://api-sni.retrotax-aci.com

Staging

  1. SNI-enabled - https://api-staging.retrotax-aci.com
  2. SNI-disabled - https://api-sni-staging.retrotax-aci.com

QA

  1. SNI-enabled - https://api-qa.retrotax-aci.com
  2. SNI-disabled - https://api-sni-qa.retrotax-aci.com

Acquiring an API Key

When making a request to our API, you must use an API key in the request header. All API requests require the X-API-KEY key/value pair in the request header. This key is used to authenticate your application in AWS API Gateway for accounting and authorization purposes. If an API key is not provided, the request will fail.

To register for an API key, please email tech@retrotax-aci.com .

If your HRIS platform manages multiple clients, we recommend using 1 API key for all accounts.

Authorization

Retrotax TCID API's uses a token-based authentication system. Retrotax assigns an API Key for your application and also username and password each for hiring manager and new hire employee.

Signing In

For authenticating with the TCID API's you will need to send a request to the authentication API.

Sample HTTP Request:

POST /authentication/ HTTP/1.1
Host: api.retrotax-aci.com
Content-Type: application/json
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJb

{
    "username": "hiring_manager",
    "password": "password123456"
}

Sample Response:

{
  "username": "hiring_manager",
  "email": "hiring_manager@gmail.com",
  "role": "hiring_manager",
  "auth_token": "0fd8b4f5f83eedbcca80d9ce53622792c82cbb5cc2d6576791f4022f7f4954c908ecdf92d92fbc95354603b4acc64cdd54b4c8cda3d889a8d15582d5d6c9773f",
  "preffered_language": "english",
  "help_checkbox": true,
  "client_name": "DemoAPI",
  "ccl_info": {
    "client_id": 364
  },
  "ats_enabled": false,
  "obs_enabled": true,
  "display_label": "RetroTax"
}

For every subsequent secure request, you must send an api key and auth token in the header of the request. The auth_token can be found in the /authentication response above.

AuthToken

For making requests to the RetroTax API on behalf of clients, you will need an authorization token (i.e. auth_token parameter), which is returned in response of sign in process.

POST /employees
Host: api.retrotax-aci.com
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJa
X-AUTH-TOKEN: 7VHJh8K6lgdh157z
Content-Type: application/json
Accept: application/json

{
  "employee_info": {
    "first_name": "Oliver",
    "last_name": "Queen"
  },
 "hiring_manager_info": { ... },
 "questionnaire": { ...}
 "..."
}

Authorization tokens are generated using "Authlogic::Random.hex_token" function. We have two types of authorization tokens:

  1. Temporary Auth Tokens are valid for 12 hours. After every 12 hours, the user will receive 401 status codes on all API requets until the user signs in again.

  2. Permanent Auth Tokens are assigned to a hiring manager's account during the user setup process. The auth token will be remain the same in its whole life span. Changing a permanent auth token must be done through a support request made to RetroTax.

For security reasons, we recommend temporary authentication tokens.

Signing Out

To sign out, please send a DELETE request to the authentication API with the auth token. On sucessful processing of the request, the auth token is invalidated and cannot be used anymore. The API key remains the same throughout your application; unless otherwised changed through a support request.

DELETE /authentication
Host: end-point-of-tcid
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJa
X-AUTH-TOKEN: 7VHJh8K6lgdh157z
Content-Type: application/json
Accept: application/json
Cache-Control: no-cache

Sample Response:

204 OK

Unauthorized Requests

For unauthorized requests with expired or incorrect API key/Auth Token, the secure API resource will send a 401 Unauthorized response.

Sample Response:

401 Unauthorized { 'Invalid credentials.'}

User Accounts

Roles & Access Levels

The RetroTax system defines two types of roles for integration partners:

  1. Hiring Managers
  2. Employees

API integrations will primarily manage users assigned with a hiring manager role. When a hiring manager is created in the RetroTax system, it is assigned an access level, which can be one of three levels: client, company, or location (CCL). As illustrated below, the access level will vary based on your integration's setup and whether you're managing multiple clients with multiple companies and locations or a single client with multiple companies and locations or a single CCL.

Client Level User Account

This diagram illustrates a client-level API user account. In this scenario, Client-Mart's API key can make requests on behalf of any of the client's associated companies and companies' locations. For example, Client-Mart can create a new record on behalf of Company-Mart-1, list the required documents for employee 8675309 in Company-Mart-2, or run a compliance report for Company-Mart-2's Location-Mart-B.

Company Level User Account

This diagram illustrates a company-level API user account. In this scenario, Company-Mart-2's API key can make requests on behalf of any of the company's associated locations. For example, Company-Mart-2 can create a new record on behalf of Location-Mart-Y, list the required documents for employee 8675309 in Company-Mart-2, or run a compliance report for Company-Mart-2's Location-Mart-Z. However, this api key cannot make requests to other companies or other companies' locations, regardless of being a part of the same parent entity (Client). As the diagram illustrates, requests made to any entity shaded in red will fail.

Location Level User Account

This diagram illustrates a location-level API user account. In this scenario, Location-Mart-Z's API key can only make requests on behalf of itself and the employees within that location. For example, Location-Mart-Z can create a new record on behalf of Location-Mart-Z, list the required documents for its employees, or run a compliance report for itself. However, this api key cannot make requests to other companies or even locations within the same parent company,Location-Mart-Y. As the diagram illustrates, requests made to any entity shaded in red will fail.

Example OBS Integration - Complex Flow

Coming Soon.

Example OBS Integration - Simple Flow

Here's an example of a "simple" obs integration can look like and how it'll flow for an HRIS integration partner managing multiple shared clients where each client might have multiple companies and/or locations.

The reason we call this a "simple flow" is simply because it combines the employee, hiring manager, and esignature steps into a single API request. Consequently, this flow requires less API calls to RetroTax's servers.

Step 1: Managing Location IDs

In order to create new employee records in the RetroTax system, a location_id parameter must be defined so that we can associate the employee to its specific location.

How you manage location IDs will be determined by your hiring manager's user account and its access level (see User Accounts section in this documentation). You will need to store the location IDs in your application, which can be retrieved once RetroTax has setup your user accounts. Call GET /companies and GET /locations to return a list of locations and their IDs.

Step 2: New Hire Completes RetroTax Questionnaire

At this point, the new hire will complete the RetroTax questionnaire. From a user perspective, the new hire will be prompted to answer the WOTC questionnaire. The following is a sample UI that would need to be created within your application. Obviously, the front-end will be customized to your application's UI. Additionally, you will need to handle validations on your front-end in order to post valid requests.

Depending upon the user's answers to the WOTC questionnaire, specific sub-questions are required, as defined in the employees resource of this documentation. The following is an example of what the user should see when answering 'yes' to being a recipient of foodstamps:

When a new hire completes the RetroTax WOTC questionnaire, s/he must authorize and e-sign. This is required. The wording of the authorization section can be slightly modified if needed. For instance, in a completely seamless API integration where RetroTax acts entirely behind the scenes, the "representative (Associated Consultants, Ind dba RetroTax)" portion of the authorization confirmation might cause confusion to any new hire who reads the entire section. For this reason, we can propose alternatives.

Step 3: Complete Hiring Manger Information

At this point, your application should populate the "hiring_manager" and "e_signatures" objects in the body of the employees POST request. By far, the easiest and most common option is to default hiring manager fields to pre-determined values that matches the client's average new hire (e.g. defaulting date started work to today's date, starting wage to $10, and a common starting position, etc). By pre-defining these values, we can reduce the number of steps in the workflow and, therefore, provide a better expreience for the end-user. In this flow, you can submit the employee's recently completed questionnaire and default hiring manager info in a single request to the RetroTax API. In order to do this, include the "e_signatures" and "hiring_manager_info" like below.

Sample POST Employees in Single Request:

POST /employees HTTP/1.1
Host: api.retrotax-aci.com
Content-Type: application/json
X-AUTH-TOKEN: 0fd8b4f5f83eedbcca80d9ce53622792c82cbb5cc2d6576791f4022f7f4954c908ecdf92d92fbc95354603b4acc64cdd54b4c8cda3d889a8d15582d5d6c9773f
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJb

{
    "employee_info": {
        "first_name": "Jane",
        "last_name": "Doe",
        "suffix":"",
        "address_line_1": "2013 W 47th St New City",
        "address_line_2": "",
        "city": "Chicago",
        "zip": "60609",
        "ssn": 237776608,
        "rehire": false,
        "state": "IL",
        "location_id": 8557,
        "dob": "1995-04-28"
    },
     "hiring_manager_info": {
        "dojo": "2016-10-14",
        "doh": "2016-10-14",
        "dsw": "2016-10-14",
        "occupation_id": "17",
        "dgi":"2016-10-14",
        "starting_wage": "14.25"
    },
    "questionnaire": {
        "ca_wia": false,
        "unemployed": false,
        "ca_farmer": false,
        "cdib": false,
        "veteran": false,
        "ca_cal_works": false,
        "afdc": false,
        "voc_rehab": false,
        "ssi": true,
        "food_stamps": false,
        "ca_misdemeanor": false,
        "ca_foster": false,
        "felon": false,
        "scfib": false
    },
    "voc_rehab_info": {
        "is_agency":"",
        "agency_name": "",
        "zip": "",
        "phone": "",
        "city": "",
        "dept_va": "",
        "county": "",
        "state": "",
        "address_line_1": "",
        "address_line_2": "",
        "ttw": ""
    },
    "felon_info": {
        "conviction_date": "",
        "release_date": "",     
        "is_federal_conviction": "",
        "is_state_conviction":"",
        "parole_officer_name": "",
        "parole_officer_phone": "",
        "state_felony": "",
        "felon_county": ""
    },
    "veteran_info": {
        "service_start": "",
        "service_stop": "",
        "disabled": "",
        "branch": ""
    },
    "foodstamps_recipient_info": {
        "name": "",
        "relationship": "",
        "county_received": "",
        "state_received": "",
        "city_received": ""
    }, 
    "afdc_recipient_info": {
       "name": "",
       "relationship": "",
       "county_received": "",
       "state_received": "",
       "city_received": ""
   },
    "unemployment_info":{
        "unemployment_compensation": "",
        "compensation_start_date": "",
        "compensation_stop_date": "",
        "unemployment_start_date": "",
        "unemployment_stop_date": ""
    },
     "e_signatures": {
        "hm_signature": {
          "name": "Elizabeth Smith",
          "title": "Senior HR",
          "esign": true,
          "authorization": true
        },
        "emp_signature": {
          "esign": true,
          "authorization": true
        }
  }
}

Step 4: Save Employee Response

At minimum, your application should save the employee_info.id value, which can be used to retrieve the employee info at a later date.

Sample Response:

{
  "employee_info": {
    "id": 1266546,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": null,
    "suffix": null,
    "address_line_1": "2013 W 47th St New City",
    "address_line_2": null,
    "city": "Chicago",
    "county": null,
    "state": "IL",
    "zip": "60609",
    "ssn": "237776608",
    "rehire": false,
    "location_id": 8557,
    "dob": "1995-04-28",
    "is_applicant": false
  },
  "application_status": {
    "code": "UN",
    "reason": "Late",
    "description": "Unusable",
    "client_help_text": "Forms with an Unusable Reason above of Not Signed (NS) or Incomplete (IN) must be corrected and received in our office no later than the 28th day after the employee's Job Started Date or it will be considered Late. Forms with an Unusable Reason above of Rehire (RH), Late (LT), Refused (RF) or Never Received (NR) cannot be resubmitted; this notice is for your information only.",
    "is_complete": false
  },
  "qualifications": [
    {
      "description": "Supplemental Security Income (SSI) Recipient",
      "code": "H",
      "abbreviation": "SSI",
      "type": "target_group"
    }
  ],
  "hiring_manager_info": {
    "dojo": "2016-10-14",
    "doh": "2016-10-14",
    "dsw": "2016-10-14",
    "occupation_id": 17,
    "dgi": "2016-10-14",
    "starting_wage": 14.25
  },
  "e_signature": [
    {
      "name": "Elizabeth Smith",
      "title": "Senior HR",
      "user": "hiring_manager"
    }
  ],
  "dates": {
    "created_at": "29-01-2017",
    "updated_at": "29-01-2017"
  },
  "zone_status": {
    "code": "NQ",
    "description": "Not Qualified"
  },
  "suppl_program_status": {
    "code": "NQ",
    "description": "Not Qualified"
  },
  "questionnaire": {
    "ca_wia": false,
    "unemployed": false,
    "ca_farmer": false,
    "cdib": false,
    "veteran": false,
    "ca_cal_works": false,
    "afdc": false,
    "voc_rehab": false,
    "ssi": true,
    "food_stamps": false,
    "ca_misdemeanor": false,
    "ca_foster": false,
    "felon": false,
    "sc_fib": false
  }
}

Step 5: Provide Supporting Documentation

At this point in the flow, your application needs to manage missing documentation for qualified records:

  1. Use RetroTax's Automated Missing Documents Emails By default, hiring managers are sent email reminders on a scheduled job which is triggered only for records that have required missing documentation.

  2. Manage documents via the RetroTax API For a seamless integration for hiring manager users, we recommend managing documents via the API for more granular control. At this point, your application should call GET Documents to check if the new hire is required to submit supporting documentation. Depending upon a variety of factors, pre-qualified employees will need to provide supporting documents to prove their eligibility and receive a certification.

Sample GET Documents:

GET /employees/1266546/documents HTTP/1.1
Host: api.retrotax-aci.com
Content-Type: application/json
X-AUTH-TOKEN: 0fd8b4f5f83eedbcca80d9ce53622792c82cbb5cc2d6576791f4022f7f4954c908ecdf92d92fbc95354603b4acc64cdd54b4c8cda3d889a8d15582d5d6c9773b
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJb

The RetroTax API automatically generates many required government forms needed to process the new hires. We return these documents in the GET Documents response. While entirely optional, you have the ability to display these forms' thumbnails on your front-end, provide download links for your hiring manager, etc.

Sample Response:

{
  "items": [
    {
      "status": "approved",
      "document_url": "https://api-documents-upload.s3.amazonaws.com/0B1XYPZR-MpMxSERwemJMRkVDdDg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDX7DQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T122022Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=b9f5867731242fbd8d5f263bbd03ca66e295078c1118550f16e369ef7d0780",
      "thumbnail_urls": {
        "small": "https://thumbnails-lambda.s3.amazonaws.com/small/0B1XYPZR-MpMxSERwemJMRkVDdDg.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDDQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T122022Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=c45d35069fbfa42ad6ce74734f2cea80edc204df6af62847fe952f1894f17fe6",
        "medium": "https://thumbnails-lambda.s3.amazonaws.com/medium/0B1XYPZR-MpMxSERwemJMRkVDdDg.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDX7DQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T122022Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=0d561b62731eb9bbea841931c16567b929f185c9e399102318ac4da5d98fa16b"
      },
      "pdf_sample": "https://s3.amazonaws.com/retrotax-public-forms/pdf/8850.pdf",
      "img_sample": "https://s3.amazonaws.com/retrotax-public-forms/img/8850.png",
      "description": "Signed IRS 8850 Form (Post 3/16)",
      "code": "8850",
      "client_help_text": ""
    }
  ]
}

Sample POST Documents:

POST /employees/1266546/documents HTTP/1.1
Host: api.retrotax-aci.com
Content-Type: application/json
X-AUTH-TOKEN: 0fd8b4f5f83eedbcca80d9ce53622792c82cbb5cc2d6576791f4022f7f4954c908ecdf92d92fbc95354603b4acc64cdd54b4c8cda3d889a8d15582d5d6c9773b
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJb
Cache-Control: no-cache

{
  "document_code":"SSI",
  "document_type": "image/png",
  "contents": "iVBORw0KGgoAAAANSUhEUgAABkgAAAAjCAYAAADfa4adAAABfGlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGAqSSwoyGFhYGDIzSspCnJ3UoiIjFJgv8PAzcDDIMRgxSCemFxc4BgQ4MOAE3y7xsAIoi/rgsxK8/x506a1fP4WNq+ZclYlOrj1gQF3SmpxMgMDIweQnZxSnJwLZOcA2TrJBUUlQPYMIFu3vKQAxD4BZIsUAR0IZN8BsdMh7A8gdhKYzcQCVhMS5AxkSwDZAkkQtgaInQ5hW4DYyRmJKUC2B8guiBvAgNPDRcHcwFLXkYC7SQa5OaUwO0ChxZOaFxoMcgcQyzB4MLgQAgIASEgBISAENheBGSAZHvFl0grBISAEBACQkAICAEhIASEgBAQAkJACAgBISAEhIAQEAJCQAhsAAEZINkAiOKFEBACQkAICAEhIASEgBAQAkJACAgBISAEhIAQEAJCQAgIASGwvQjIAMn2ii+RVggIASEgBISAEBACQkAICAEhIASEgBAQAkJACAgBISAEhIAQ2AACMkCyASzWMtIQkBISAEhIAQEAJCQAgIASEgBISAEBACQkAICAEhIASEgBAQAluEwP8Hq8mgAktaecoAAAAASUVORK5CYII="
}

Sample Response:

{
  "items": [
    {
      "status": "missing",
      "document_url": "",
      "thumbnail_urls": "",
      "pdf_sample": "https://s3.amazonaws.com/retrotax-public-forms/pdf/ATV.pdf",
      "img_sample": "https://s3.amazonaws.com/retrotax-public-forms/img/ATV.png",
      "description": "Signed Form A or Signed ATV",
      "code": "FORM A",
      "client_help_text": "Signed Form A or ATV: a signed general release of information form. It allows us to pursue different types of documentation from outside agencies if the employee is unable to provide it. (Please send regardless of employment status.)"
    },
    {
      "status": "pending",
      "document_url": "https://api-documents-upload.s3.amazonaws.com/0B1XYPZR-MpMxN253am9WQ1dUU1k?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDX7DQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T124125Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=4da15da28c3c8b6bb946af9bc8c13525b9bb7fe6962ce52d7b5f68dffd3512f6",
      "thumbnail_urls": {},
      "pdf_sample": "https://s3.amazonaws.com/retrotax-public-forms/pdf/SSI.pdf",
      "img_sample": "https://s3.amazonaws.com/retrotax-public-forms/img/SSI.png",
      "description": "Proof of SSI",
      "code": "SSI",
      "client_help_text": "Proof of SSI: (Supplemental Security Income, not a Social Security card) benefits verification can be any of the following: SSI check stub, SSI Record or Authorization contact, or an award letter."
    }
  ]
}

Example ATS Integration

Applicant Tracking System (ATS) integrations allow partnering HRIS platforms to pre-screen applicants for tax credits before the applicant has been hired. From a hiring perspective, this will tell you which applicants should eventually qualify, assuming s/he is hired. There are 3 aspects that differentiate this ATS request from the OBS request.

  1. The "is_applicant" parameter is defined and set to true in the "employee_info" object.
  2. "hiring_manager" object is absent from the request.
  3. "e_signatures" object is absent from the request.

Sample ATS request:

POST /employees HTTP/1.1
Host: api.retrotax-aci.com
Content-Type: application/json
X-AUTH-TOKEN: 2867df3f4b718a521d6650d51dd2f5dc74dc056a3a5760c83febd7f5c76f173b460c66a4dba97105d6a77a2d74c84b441876d07812d3a4cc0aa3ae4ed7babed
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJb
{
    "employee_info": {
        "first_name": "Test",
        "last_name": "Employee",
        "suffix":"",
        "address_line_1": "9110 JDrive",
        "address_line_2": "UTC",
        "city": "San Diego",
        "zip": "92122",
        "ssn": "826330020",
        "rehire": false,
        "state": "AL",
        "location_id": 5463,
        "dob": "2000-04-28",
        "is_applicant":true
    },
    "questionnaire": {
        "ca_wia": false,
        "unemployed": false,
        "ca_farmer": false,
        "cdib": false,
        "veteran": false,
        "ca_cal_works": false,
        "afdc": false,
        "voc_rehab": false,
        "ssi": true,
        "food_stamps": false,
        "ca_misdemeanor": false,
        "ca_foster": false,
        "felon": false,
        "scfib": false
    },
    "voc_rehab_info": {
        "is_agency": true,
        "agency_name": "foo",
        "zip": "92122",
        "phone": "foo",
        "city": "foo",
        "dept_va": true,
        "county": "foo",
        "state": "AK",
        "address_line_1": "foo",
        "address_line_2": "foo",
        "ttw": true
    },
    "felon_info": {
        "conviction_date": "2014-01-28",
        "release_date": "2014-01-28",     
        "is_federal_conviction": true,
        "is_state_conviction": true,
        "parole_officer_name": "Robert",
        "parole_officer_phone": "9933244444",
        "state_felony": "MI",
        "felon_county": "ALASKA"
    },
    "veteran_info": {
        "service_start": "2016-01-28",
        "service_stop": "2016-01-28",
        "disabled": true,
        "branch": "Army"
    },
    "foodstamps_recipient_info": {
        "name": "foo",
        "relationship": "foo",
        "county_received": "foo",
        "state_received": "foo",
        "city_received": "foo"
    }, 
    "afdc_recipient_info": {
       "name": "Rozar",
       "relationship": "foo",
       "county_received": "foo",
       "state_received": "AK",
       "city_received": "foo"
   },
    "unemployment_info":{
        "unemployment_compensation": true,
        "compensation_start_date": "2016-04-28",
        "compensation_stop_date": "2016-04-28",
        "unemployment_start_date": "2016-04-28",
        "unemployment_stop_date": "2016-04-28"
    }
}

Once an applicant has been hired, applicants must be 'converted' to employees so that RetroTax can process the new hire. Update applicants to employees by submitting a PUT request with the e-signature and hiring manager information like the sample HTTP request below:

PUT /employees/123456789 HTTP/1.1
Host: api.retrotax-aci.com
Content-Type: application/json
X-AUTH-TOKEN: 82292d07a1644ed147fde45a16b8d52d3b22a2188fa592d4888908a01ad2c96bdd689a124e974eabe958edd25605fd39df919cbdfecd6b3c99948c707a60
X-API-KEY: yqvNrVR5Cs6vhLq1ZRPq38GM5OrXJ7C97n4BZCJb
{
  "e_signatures": {
      "hm_signature": {
        "name": "John Doe",
        "title": "Senior HR",
        "esign": true,
        "authorization": true
      },
      "emp_signature": {
        "esign": true,
        "authorization": true
      }
    }
}

Embedded PDF Integration

Screening via PDF / Fillable Form Fields

As an alternative to creating a custom UI to screen applicants or new hires, some HRIS integrations embed RetroTax's Form A into their HRIS' onboarding process. The fillable form fields in the PDF can then be parsed and mapped to the API. The following spreadsheet can be used as a reference for determining which questions in the Form A corrrespond to parameters in the Employees POST method that's called when creating a new hire:

Mapping Template for the Form A and API fields

RetroTax's Form A

Documents

File Generation

Coming Soon.

Thumbnails

Coming Soon.

Sample GET Documents response:

{
  "items": [
    {
      "status": "approved",
      "document_url": "https://api-documents-upload.s3.amazonaws.com/0B1XYPZR-MpMxSERwemJMRkVDdDg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDX7DQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T122022Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=b9f586c87731242fbd8d5f263bbd03ca66e295078c1118550f16e369ef7d0780",
      "thumbnail_urls": {
        "small": "https://thumbnails-lambda.s3.amazonaws.com/small/0B1XYPZR-MpMxSERwemJMRkVDdDg.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDX7DQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T122022Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=c45d35069fbfa42ad6ce74734f2cea80edc204df6af62847fe952f1894f17fe6",
        "medium": "https://thumbnails-lambda.s3.amazonaws.com/medium/0B1XYPZR-MpMxSERwemJMRkVDdDg.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIHYEDX5RUDX7DQKQ%2F20170129%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170129T122022Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=0d561b62731eb9bbea841931c16567b929f185c9e399102318ac4da5d98fa16e"
      },
      "pdf_sample": "https://s3.amazonaws.com/retrotax-public-forms/pdf/8850.pdf",
      "img_sample": "https://s3.amazonaws.com/retrotax-public-forms/img/8850.png",
      "description": "Signed IRS 8850 Form (Post 3/16)",
      "code": "8850",
      "client_help_text": ""
    }
  ]
}

Security

Overview

RetroTax takes security seriously. We develop our applications with known security standards in mind (OWASP). Our security documentation extends beyond the scope of this API's documentation, as it covers personel security, operational, network, application, authentication, data, physical, etc. However, RetroTax can provide our implementation partners more detailed documentation of our security practices and policies upon request.

Authentication

The RetroTax Application utilizes Authlogic and Pundit for authentication and authorization. For this we used authlogic gem, which uses default encryption type SCrypt to store the passwords.

Encryption, SSL

The RetroTax API uses 2048-bit RSA with SHA-256 as a secure signing scheme. Data in transit and at rest is encrypted using AES-256 encryption algorithm.

3rd Party Auditing

RetroTax conducts annual 3rd party application penetration tests on our API.