Skip to main content
Version: 1.6.1

Create

Creates New Hire reports with an unique Submission Id which is further used for all other methods referencing these New Hire reports.

POST NewHireReport/Create

Request Body

FieldTypeDescription
NHReportsobject[]Object to create New Hire reports.
    SequencestringA unique number given by an inbound application to identify failed records.
Size Range: ..60
    ReportingToStateCdstringState code of the New Hire Reporting State
Size Range: 2
    EmployeeCntnumberNumber of Employees for New Hire Reporting
    EmployerobjectEmployer details
        BusinessIdGuidUnique Identifier of the business
        BusinessNmstringName of the business
Size Range: ..75
        TradeNmstringOptional Name under which the business operates
Size Range: ..75
        IsEINBooleanWhen true, identifies the business with an EIN.
        EINorSSNstringWhen IsEIN is true, use Employer Identification Number (EIN). When IsEIN is false, use Social Security Number (SSN)
Size Range: 9
        EmailstringEmail address of the Business
Size Range: ..40
        ContactNmstringOptional Name of the person who can be contacted by the IRS
Size Range: ..27
        PhonestringContact number of the business with area code
Size Range: 10
        PhoneExtnstringOptional Extension of the business phone number
Size Range: ..5
        FaxstringOptional Fax number of the Business
Size Range: 10
        BusinessTypestringType of business. Optional for W-2/1099 and mandatory for 94X series
Size Range: ..4
Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
        KindOfEmployerstringIdentifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series.
Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
        KindOfPayerstringIdentifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series.
Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
        IsBusinessTerminatedBooleanWhen true, identifies the business as terminated.
        IsForeignBooleanWhen true, identifies the business address with a foreign address.
        USAddressobjectif IsForeign is false, pass US address of the business
            Address1stringEmployer/Payer's US address (street address or post office box of that locality)
Size Range: ..35
            Address2stringOptional Employer/Payer's suite or apartment
Size Range: ..35
            CitystringEmployer/Payer's city
Size Range: ..27
            StatestringState code of the employer/payer. Refer Static values.
Size Range: 2
Allowed values: "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"
            ZipCdstringEmployer/Payer's zip code
        ForeignAddressobjectif IsForeign is true, pass foreign address of the business
            Address1stringEmployer/Payer's foreign address (street address or post office box of that locality)
Size Range: ..35
            Address2stringOptional Employer/Payer's suite or apartment
Size Range: ..35
            CitystringEmployer/Payer's city
Size Range: ..27
            ProvinceOrStateNmstringEmployer/Payer's province or state name
Size Range: ..30
                CountrystringEmployer/Payer country code. Refer Static values.
Size Range: 2
Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
            PostalCdstringEmployer/Payer's postal code
    Employeesobject[]Object to identify the employee details
        SequencestringEmployee's sequence number.
Size Range: ..60
        SSNstringEmployee's Social Security Number (SSN)
Size Range: 9
        FirstNmstringEmployee's First Name
Size Range: ..15
        MiddleNmstringEmployee's Middle Name
Size Range: ..15
        LastNmstringEmployee's Last Name
Size Range: ..20
        SuffixstringEmployee's Suffix.
Size Range: ..3
        EmailstringEmployee's email address.
Size Range: ..40
        FaxstringEmployee's Fax number.
Size Range: 10
        PhonestringEmployee's phone number including area code.
Size Range: 10
        USAddressobjectObject to identify the employee's US address
            Address1stringEmployee's US address (street address or post office box of that locality)
Size Range: ..35
            Address2stringOptional Employee's suite or apartment
Size Range: ..35
            CitystringEmployee's city
Size Range: ..27
            StatestringEmployee's state code. Refer Static values.
Size Range: 2
Allowed values: "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP"
            ZipCdstringEmployee's zip code.
        StateSpecificsnumberState specified information for New Hire reporting.
            DOBDateTimeEmployee's Date of Birth
            DtOfRemunerationDateTimeEmployee's Date of Remuneration
        EmployeeUIdGuidUnique Identifier of an Employee
        HireTypestringHire type of an employee. Applicable only for New Hires.
    RecordIdGuidUnique Identifier of a record

Response Body

FieldTypeDescription
StatusCodenumberReturns the HTTP status codes like 200,300 etc.
StatusNamestringName of the status code.
StatusMessagestringDetailed status message.
SubmissionIdGuidUnique identifier of a submission.
NHReportsobjectPulls the New Hire report records with Success and Error statuses
    SuccessRecordsobject[]It will show the detailed information about the success status of New Hire Report Records
        SequencestringA unique number given by an inbound application to identify failed records.
        RecordIdGuidUnique identifier of a record
        RecordStatusstringReturns the status of the records.
        EmployeeRecordsstringReturn status details like Created, Transmitted, Accepted, Rejected.
            SequencestringA unique number given by an inbound application to identify failed records.
            EmployeeUIdGuidUnique identifier of an Employee
            StatusstringReturns the status of the Employee details.
        CreatedTsDateTimeDate and time of return created.
        UpdatedTsDateTimeDate and time of return updated.
    ErrorRecordsobject[]It will show the detailed information about the error status of New Hire Report Records
        SequencestringA unique number given by an inbound application to identify failed records.
        RecordIdGuidUnique identifier of a record
        Errorsobject[]Shows detailed error information.
            CodestringReturns the validation error code.
            NamestringName of the validation error.
            MessagestringDescription of the validation error.
            TypestringType of validation error.
        EmployeeErrorRecordsobject[]Return status details like Created, Transmitted, Accepted, Rejected.
            SequencestringA unique number given by an inbound application to identify failed records
            EmployeeUIdGuidClient Record Identifier
            Errorsobject[]Shows detailed error information.
                CodestringReturns the validation error code.
                NamestringName of the validation error.
                MessagestringDescription of the validation error.
                TypestringType of validation error.
Errorsobject[]Shows detailed error information.
    CodestringReturns the validation error code.
    NamestringName of the validation error.
    MessagestringDescription of the validation error.
    TypestringType of validation error

Request JSON

{   "NHReports": [       {           "Sequence": "1",           "ReportingToStateCd": "SC",           "EmployeeCnt": 2,           "Employer": {               "BusinessId": null,               "BusinessNm": "Eastman Kodak Company",               "TradeNm": "Kodak",               "IsEIN": true,               "EINorSSN": "003333330",               "Email": "john@gmail.com",               "ContactNm": "John",               "Phone": "1234567890",               "PhoneExtn": "12345",               "Fax": "1234567890",               "BusinessType": "ESTE",               "SigningAuthority": {                   "Name": "John",                   "Phone": "1234567890",                   "BusinessMemberType": "ADMINISTRATOR"               },               "KindOfEmployer": null,               "KindOfPayer": null,               "IsBusinessTerminated": false,               "IsForeign": false,               "USAddress": {                   "Address1": "1751 Kinsey Rd",                   "Address2": "Main St",                   "City": "Dothan",                   "State": "AL",                   "ZipCd": "36303"               },               "ForeignAddress": null           },           "Employees": [               {                   "Sequence": "1",                   "SSN": "393848035",                   "FirstNm": "John",                   "MiddleNm": "F",                   "LastNm": "Kennedy",                   "Suffix": "Mr",                   "Email": "john@gmail.com",                   "Fax": "1234567890",                   "Phone": "1234567890",                   "USAddress": {                       "Address1": "1751 Kinsey Rd",                       "Address2": "Main St",                       "City": "Dothan",                       "State": "AL",                       "ZipCd": "36303"                   },                   "StateSpecifics": {                       "DOB": "1992-05-10T10:50:19.4269819-04:00",                       "DtOfRemuneration": "2019-05-10T10:50:19.4269819-04:00"                   },                   "EmployeeUId": null,                   "HireType": "NEWHIRE"               },               {                   "Sequence": "2",                   "SSN": "393848039",                   "FirstNm": "Fred",                   "MiddleNm": "F",                   "LastNm": "Thomas",                   "Suffix": "Mr",                   "Email": "john@gmail.com",                   "Fax": "1234567890",                   "Phone": "1234567890",                   "USAddress": {                       "Address1": "1751 Kinsey Rd",                       "Address2": "Main St",                       "City": "Dothan",                       "State": "AL",                       "ZipCd": "36303"                   },                   "StateSpecifics": {                       "DOB": "1992-05-10T10:50:19.4269819-04:00",                       "DtOfRemuneration": "2019-05-10T10:50:19.4269819-04:00"                   },                   "EmployeeUId": null,                   "HireType": "NEWHIRE"               }           ],           "RecordId": null       }   ]}

Response JSON

{   "StatusCode": 200,   "StatusName": "Ok",   "StatusMessage": "Successful API call",   "SubmissionId": "31eb9b80-a935-4204-b32c-14db8d99a57e",   "NHReports": {       "SuccessRecords": [           {               "Sequence": "1",               "RecordId": "2ffde35c-c885-45c6-ab48-424a89c838ed",               "RecordStatus": "Created",               "EmployeeRecords": [                   {                       "Sequence": "1",                       "EmployeeUId": "b20c15ce-1ff5-44aa-a470-9876102736e4",                       "Status": "Created"                   },                   {                       "Sequence": "2",                       "EmployeeUId": "6ee31144-c0db-48da-a82b-f798342e6e58",                       "Status": "Created"                   }               ],               "CreatedTs": "2019-08-02 08:36:04 -04:00",               "UpdatedTs": "2019-08-02 08:36:04 -04:00"           }       ],       "ErrorRecords": null   },   "Errors": null}