{
  "type": "object",
  "required": [
    "benefit_id",
    "tax_year",
    "ytd_employee_deduction_amount",
    "ytd_company_contribution_amount"
  ],
  "properties": {
    "tax_year": {
      "type": "number",
      "maximum": 2999,
      "minimum": 2000,
      "description": "The tax year for which this amount applies."
    },
    "benefit_type": {
      "type": "number",
      "description": "The benefit type supported by Gusto."
    },
    "ytd_employee_deduction_amount": {
      "type": "string",
      "default": "0.00",
      "description": "The year-to-date employee deduction made outside the current company."
    },
    "ytd_company_contribution_amount": {
      "type": "string",
      "default": "0.00",
      "description": "The year-to-date company contribution made outside the current company."
    }
  }
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Employee-Benefit"
  }
}

{
  "type": "object",
  "required": [
    "version"
  ],
  "properties": {
    "active": {
      "type": "boolean",
      "description": "Whether the employee benefit is active."
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field."
    },
    "catch_up": {
      "type": "boolean",
      "default": false,
      "description": "Whether the employee should use a benefit’s \"catch up\" rate. Only Roth 401k and 401k benefits use this value for employees over 50."
    },
    "elective": {
      "type": "boolean",
      "default": false,
      "description": "Whether the company contribution is elective (aka \"matching\"). For `tiered`, `elective_amount`, and `elective_percentage` contribution types this is ignored and assumed to be `true`."
    },
    "contribution": {
      "type": "object",
      "properties": {
        "type": {
          "enum": [
            "amount",
            "percentage",
            "tiered"
          ],
          "type": "string",
          "description": "The company contribution scheme.\n\n`amount`: The company contributes a fixed amount per payroll. If elective is true, the contribution is matching, dollar-for-dollar.\n\n`percentage`: The company contributes a percentage of the payroll amount per payroll period. If elective is true, the contribution is matching, dollar-for-dollar.\n\n`tiered`: The size of the company contribution corresponds to the size of the employee deduction relative to a tiered matching scheme."
        },
        "value": {
          "oneOf": [
            {
              "type": "string",
              "description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage."
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "rate": {
                    "type": "string",
                    "description": "The percentage of employee deduction within this tier the company contribution will match."
                  },
                  "threshold": {
                    "type": "string",
                    "description": "The percentage threshold at which this tier ends (inclusive).\n\nFor example, a value of \"5\" means the company contribution will match employee deductions from the previous tier's threshold up to and including 5% of payroll.\n\nIf this is the first tier, a value of \"5\" means the company contribution will match employee deductions from 0% up to and including 5% of payroll."
                  }
                },
                "description": "A single tier of a tiered matching scheme."
              },
              "description": "For `tiered` contribution types, an array of tiers."
            }
          ],
          "description": "For the `amount` and `percentage` contribution types, the value of the corresponding amount or percentage.\n\nFor the `tiered` contribution type, an array of tiers."
        }
      },
      "description": "An object representing the type and value of the company contribution."
    },
    "limit_option": {
      "type": "string",
      "nullable": true,
      "description": "Some benefits require additional information to determine their limit. For example, for an HSA benefit, the limit option should be either \"Family\" or \"Individual\". For a Dependent Care FSA benefit, the limit option should be either \"Joint Filing or Single\" or \"Married and Filing Separately\"."
    },
    "coverage_amount": {
      "type": "string",
      "nullable": true,
      "description": "The amount that the employee is insured for. Note: company contribution cannot be present if coverage amount is set."
    },
    "employee_deduction": {
      "type": "string",
      "default": "0.00",
      "description": "The amount to be deducted, per pay period, from the employee's pay."
    },
    "company_contribution": {
      "type": "string",
      "default": "0.00",
      "deprecated": true,
      "description": "The amount to be paid, per pay period, by the company."
    },
    "deduct_as_percentage": {
      "type": "boolean",
      "description": "Whether the employee deduction amount should be treated as a percentage to be deducted from each payroll."
    },
    "contribute_as_percentage": {
      "type": "boolean",
      "default": false,
      "deprecated": true,
      "description": "Whether the company contribution amount should be treated as a percentage to be deducted from each payroll."
    },
    "coverage_salary_multiplier": {
      "type": "string",
      "default": "0.00",
      "description": "The coverage amount as a multiple of the employee’s salary. Only applicable for Group Term Life benefits. Note: cannot be set if coverage amount is also set."
    },
    "deduction_reduces_taxable_income": {
      "enum": [
        "unset",
        "reduces_taxable_income",
        "does_not_reduce_taxable_income",
        null
      ],
      "type": "string",
      "default": "unset",
      "nullable": true,
      "description": "Whether the employee deduction reduces taxable income or not. Only valid for Group Term Life benefits. Note: when the value is not \"unset\", coverage amount and coverage salary multiplier are ignored."
    },
    "employee_deduction_annual_maximum": {
      "type": "string",
      "nullable": true,
      "description": "The maximum employee deduction amount per year. A null value signifies no limit."
    },
    "company_contribution_annual_maximum": {
      "type": "string",
      "nullable": true,
      "description": "The maximum company contribution amount per year. A null value signifies no limit."
    }
  }
}

{
  "type": "object",
  "required": [
    "effective_date"
  ],
  "properties": {
    "effective_date": {
      "type": "string",
      "description": "The employee's last day of work."
    },
    "run_termination_payroll": {
      "type": "boolean",
      "description": "If true, the employee should receive their final wages via an off-cycle payroll. If false, they should receive their final wages on their current pay schedule."
    }
  },
  "description": ""
}

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "hire_date": {
        "type": "string",
        "description": "The employee's start day of work for an employment."
      },
      "termination_date": {
        "type": "string",
        "description": "The employee's last day of work for an employment."
      },
      "employment_status": {
        "enum": [
          "part_time",
          "full_time",
          "part_time_eligible",
          "variable",
          "seasonal",
          "not_set"
        ],
        "type": "string",
        "description": "The employee's employment status. Supplying an invalid option will set the employment_status to *not_set*."
      },
      "file_new_hire_report": {
        "type": "boolean",
        "description": "The boolean flag indicating whether Gusto will file a new hire report for the employee."
      },
      "two_percent_shareholder": {
        "type": "boolean",
        "description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
      }
    },
    "x-examples": {
      "example-1": {
        "hire_date": "2023-01-30",
        "termination_date": "2023-03-30",
        "employment_status": "seasonal",
        "file_new_hire_report": false,
        "two_percent_shareholder": false
      }
    }
  }
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Termination"
  }
}

{
  "allOf": [
    {
      "$ref": "#/components/schemas/Versionable-Required"
    },
    {
      "$ref": "#/components/schemas/Rehire-Body"
    }
  ]
}

{
  "allOf": [
    {
      "$ref": "#/components/schemas/Versionable-Required"
    },
    {
      "type": "object",
      "required": [
        "effective_date"
      ],
      "properties": {
        "effective_date": {
          "type": "string",
          "description": "The employee's last day of work."
        },
        "run_termination_payroll": {
          "type": "boolean",
          "description": "If true, the employee should receive their final wages via an off-cycle payroll. If false, they should receive their final wages on their current pay schedule."
        }
      },
      "description": ""
    }
  ]
}

{
  "type": "object",
  "required": [
    "employee_id"
  ],
  "properties": {
    "year": {
      "type": "integer",
      "description": "Must be equal to or more recent than 2015. If not specified, defaults to the previous year.\n"
    },
    "employee_id": {
      "type": "string",
      "description": "The employee UUID."
    }
  }
}

{
  "allOf": [
    {
      "properties": {
        "employee_uuid": {
          "type": "string",
          "readOnly": true,
          "description": "The UUID of the employee"
        }
      }
    },
    {
      "$ref": "#/components/schemas/Form"
    }
  ]
}

{
  "type": "object",
  "required": [
    "signature_text",
    "agree",
    "signed_by_ip_address"
  ],
  "properties": {
    "agree": {
      "type": "boolean",
      "description": "whether you agree to sign electronically"
    },
    "signature_text": {
      "type": "string",
      "description": "The signature"
    },
    "signed_by_ip_address": {
      "type": "string",
      "description": "The IP address of the signatory who signed the form."
    }
  },
  "description": ""
}

{
  "type": "object",
  "required": [
    "name",
    "routing_number",
    "account_number",
    "account_type"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "account_type": {
      "enum": [
        "Checking",
        "Savings"
      ],
      "type": "string"
    },
    "account_number": {
      "type": "string"
    },
    "routing_number": {
      "type": "string"
    }
  }
}

{
  "type": "object",
  "properties": {}
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Employee-Bank-Account"
  }
}

{
  "type": "object",
  "required": [
    "version",
    "type"
  ],
  "properties": {
    "type": {
      "enum": [
        "Direct Deposit",
        "Check"
      ],
      "type": "string",
      "description": "The payment method type. If type is Check, then split_by and splits do not need to be populated. If type is Direct Deposit, split_by and splits are required."
    },
    "splits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The bank account name"
          },
          "uuid": {
            "type": "string",
            "description": "The bank account ID\n"
          },
          "priority": {
            "type": "integer",
            "description": "The order of priority for each payment split, with priority 1 being the first bank account paid. Priority must be unique and sequential."
          },
          "split_amount": {
            "type": "integer",
            "nullable": true,
            "description": "The cents amount allocated for each payment split"
          }
        }
      }
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field."
    },
    "split_by": {
      "enum": [
        "Amount",
        "Percentage"
      ],
      "type": "string",
      "description": "Describes how the payment will be split. If split_by is Percentage, then the split amounts must add up to exactly 100. If split_by is Amount, then the last split amount must be nil to capture the remainder."
    }
  }
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Employee-State-Tax"
  }
}

{
  "type": "object",
  "required": [
    "version"
  ],
  "properties": {
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field."
    },
    "two_jobs": {
      "type": "boolean"
    },
    "deductions": {
      "type": "string"
    },
    "other_income": {
      "type": "string"
    },
    "w4_data_type": {
      "type": "string"
    },
    "filing_status": {
      "type": "string"
    },
    "dependents_amount": {
      "type": "string"
    },
    "extra_withholding": {
      "type": "string",
      "nullable": true
    }
  },
  "description": ""
}

{
  "type": "object",
  "required": [
    "states"
  ],
  "properties": {
    "states": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "state"
        ],
        "properties": {
          "state": {
            "type": "string"
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "key"
              ],
              "properties": {
                "key": {
                  "type": "string"
                },
                "answers": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "value",
                      "valid_from"
                    ],
                    "properties": {
                      "value": {
                        "type": "string"
                      },
                      "valid_from": {
                        "type": "string"
                      },
                      "valid_up_to": {
                        "nullable": true
                      }
                    }
                  },
                  "uniqueItems": true
                }
              }
            },
            "uniqueItems": true
          }
        }
      },
      "uniqueItems": true
    }
  },
  "x-examples": {
    "example-1": {
      "states": [
        {
          "state": "CA",
          "questions": [
            {
              "key": "filing_status",
              "answers": [
                {
                  "value": "M",
                  "valid_from": "2010-01-01",
                  "valid_up_to": null
                }
              ]
            },
            {
              "key": "withholding_allowance",
              "answers": [
                {
                  "value": 2,
                  "valid_from": "2010-01-01",
                  "valid_up_to": null
                }
              ]
            },
            {
              "key": "additional_withholding",
              "answers": [
                {
                  "value": "25.0",
                  "valid_from": "2010-01-01",
                  "valid_up_to": null
                }
              ]
            }
          ]
        }
      ]
    }
  },
  "description": ""
}

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "state",
      "questions"
    ],
    "properties": {
      "state": {
        "type": "string"
      },
      "questions": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "key"
          ],
          "properties": {
            "key": {
              "type": "string"
            },
            "answers": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "valid_from"
                ],
                "properties": {
                  "errors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "valid_from": {
                    "type": "string"
                  },
                  "valid_up_to": {
                    "nullable": true
                  }
                }
              },
              "uniqueItems": true
            }
          }
        },
        "uniqueItems": true
      }
    }
  },
  "x-examples": {
    "example-1": [
      {
        "state": "CA",
        "questions": [
          {
            "key": "filing_status",
            "answers": [
              {
                "errors": [
                  "string"
                ],
                "valid_from": "2010-01-01",
                "valid_up_to": null
              }
            ]
          }
        ]
      }
    ]
  },
  "description": "",
  "uniqueItems": true
}

{
  "type": "object",
  "required": [
    "first_name",
    "last_name"
  ],
  "properties": {
    "ssn": {
      "type": "string",
      "pattern": "[0-9]{9}"
    },
    "email": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "first_name": {
      "type": "string"
    },
    "date_of_birth": {
      "type": "string"
    },
    "middle_initial": {
      "type": "string"
    },
    "self_onboarding": {
      "type": "boolean",
      "description": "If true, employee is expected to self-onboard. If false, payroll admin is expected to enter in the employee's onboarding information"
    }
  },
  "description": ""
}

{
  "type": "object",
  "properties": {
    "custom_fields": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Employee-Custom-Field"
      }
    }
  }
}

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {}
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Employee"
  }
}

{
  "type": "object",
  "required": [
    "version"
  ],
  "properties": {
    "ssn": {
      "type": "string",
      "pattern": "[0-9]{9}"
    },
    "email": {
      "type": "string"
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field."
    },
    "last_name": {
      "type": "string"
    },
    "first_name": {
      "type": "string"
    },
    "date_of_birth": {
      "type": "string"
    },
    "middle_initial": {
      "type": "string"
    },
    "two_percent_shareholder": {
      "type": "boolean",
      "description": "Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type."
    }
  },
  "description": ""
}

{
  "type": "object",
  "required": [
    "onboarding_status"
  ],
  "properties": {
    "onboarding_status": {
      "type": "string",
      "description": "The updated onboarding status for the employee"
    }
  }
}

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "description": "Unique identifier for the event."
    },
    "timestamp": {
      "type": "integer",
      "description": "Time at which this event was created. Measured in seconds since the Unix epoch."
    },
    "event_type": {
      "type": "string",
      "description": "Description of the event (e.g., payroll.submitted, or company.form.signed)."
    },
    "entity_type": {
      "type": "string",
      "description": "Name of the entity that the event corresponds to."
    },
    "entity_uuid": {
      "type": "string",
      "description": "Unique identifier for the entity."
    },
    "resource_type": {
      "enum": [
        "Company"
      ],
      "type": "string",
      "description": "Name of the parent resource of the described entity."
    },
    "resource_uuid": {
      "type": "string",
      "description": "Unique identifier for the parent resource."
    }
  },
  "x-examples": {
    "example": {
      "uuid": "f7397a24-57ad-4fae-b011-d258e8232900",
      "timestamp": 1686784995,
      "event_type": "employee.bank_account.created",
      "entity_type": "BankAccount",
      "entity_uuid": "92a20431-9489-4bde-ad27-6feb20b969d5",
      "resource_type": "Company",
      "resource_uuid": "92a20431-9489-4bde-ad27-6feb20b969d5"
    }
  },
  "description": "Representation of an Event"
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Event"
  }
}

{
  "type": "object",
  "title": "",
  "x-tags": [
    "External Payrolls"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the external payroll."
    },
    "status": {
      "enum": [
        "unprocessed",
        "processed"
      ],
      "type": "string",
      "readOnly": true,
      "description": "The status of the external payroll. The status will be `unprocessed` when the external payroll is created and transition to `processed` once tax liabilities are entered and finalized.  Once in the `processed` status all actions that can edit an external payroll will be disabled."
    },
    "metadata": {
      "type": "object",
      "readOnly": true,
      "properties": {
        "deletable": {
          "type": "boolean",
          "readOnly": true,
          "description": "Determines if the external payroll can be deleted."
        }
      },
      "description": "Stores metadata of the external payroll."
    },
    "check_date": {
      "type": "string",
      "readOnly": true,
      "description": "External payroll's check date."
    },
    "company_uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the company."
    },
    "applicable_taxes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "employer_tax": {
            "type": "boolean",
            "description": "Some taxes may have an amount withheld from the employee and an amount withheld from the employer, e.g. Social Security. A `true` value indicates this is the employer's amount."
          },
          "resident_tax": {
            "type": "boolean",
            "description": "Some taxes may have different rates or reporting requirements depending on if the employee is a resident or non-resident of the tax jurisdiction."
          }
        }
      },
      "readOnly": true,
      "description": "Applicable taxes based on company provisioning."
    },
    "applicable_benefits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "active": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "readOnly": true,
      "description": "Applicable benefits based on company provisioning."
    },
    "applicable_earnings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "earning_id": {
            "type": "number"
          },
          "input_type": {
            "type": "string"
          },
          "earning_type": {
            "type": "string"
          }
        }
      },
      "readOnly": true,
      "description": "Applicable earnings based on company provisioning."
    },
    "external_payroll_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "taxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "amount": {
                  "type": "string",
                  "format": "float"
                },
                "tax_id": {
                  "type": "integer"
                }
              }
            }
          },
          "benefits": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "benefit_id": {
                  "type": "integer"
                },
                "employee_deduction_amount": {
                  "type": "string",
                  "format": "float"
                },
                "company_contribution_amount": {
                  "type": "string",
                  "format": "float"
                }
              }
            }
          },
          "earnings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "hours": {
                  "type": "string",
                  "format": "float"
                },
                "amount": {
                  "type": "string",
                  "format": "float"
                },
                "earning_id": {
                  "type": "integer"
                },
                "earning_type": {
                  "type": "string"
                }
              }
            }
          },
          "employee_uuid": {
            "type": "string"
          }
        }
      },
      "readOnly": true,
      "description": "External payroll items for employees"
    },
    "payment_period_end_date": {
      "type": "string",
      "readOnly": true,
      "description": "External payroll's pay period end date."
    },
    "payment_period_start_date": {
      "type": "string",
      "readOnly": true,
      "description": "External payroll's pay period start date."
    }
  },
  "x-examples": {
    "Example": {
      "uuid": "c5fdae57-5483-4529-9aae-f0edceed92d4",
      "status": "unprocessed",
      "metadata": {
        "deletable": true
      },
      "check_date": "2022-06-03",
      "company_uuid": "bcb305b0-2855-4025-8d22-e484a9e6b7c9",
      "applicable_taxes": [
        {
          "id": 1,
          "name": "Federal Income Tax",
          "employer_tax": false,
          "resident_tax": false
        },
        {
          "id": 2,
          "name": "Social Security",
          "employer_tax": false,
          "resident_tax": false
        }
      ],
      "applicable_benefits": [
        {
          "id": 22,
          "active": true,
          "description": "Kaiser"
        },
        {
          "id": 25,
          "active": true,
          "description": "HSA"
        }
      ],
      "applicable_earnings": [
        {
          "name": "Regular Wages",
          "category": "default",
          "earning_id": 1,
          "input_type": "amount",
          "earning_type": "CompanyPayType"
        },
        {
          "name": "Cash Tips",
          "category": "default",
          "earning_id": 4,
          "input_type": "amount",
          "earning_type": "CompanyEarningType"
        }
      ],
      "external_payroll_items": [
        {
          "taxes": [
            {
              "amount": 400,
              "tax_id": 1
            },
            {
              "amount": 60,
              "tax_id": 2
            }
          ],
          "benefits": [
            {
              "benefit_id": 22,
              "employee_deduction_amount": 50,
              "company_contribution_amount": 100
            },
            {
              "benefit_id": 25,
              "employee_deduction_amount": 300,
              "company_contribution_amount": 0
            }
          ],
          "earnings": [
            {
              "hours": 0,
              "amount": 10000,
              "earning_id": 1,
              "earning_type": "CompanyPayType"
            },
            {
              "hours": 0,
              "amount": 500,
              "earning_id": 4,
              "earning_type": "CompanyEarningType"
            }
          ],
          "employee_uuid": "44f7cba9-7a3d-4f08-b7bd-6fcf5211f8ca"
        }
      ],
      "payment_period_end_date": "2022-05-30",
      "payment_period_start_date": "2022-05-15"
    }
  },
  "description": "The representation of an external payroll."
}

{
  "type": "object",
  "title": "",
  "x-tags": [
    "External Payrolls"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the external payroll."
    },
    "status": {
      "enum": [
        "unprocessed",
        "processed"
      ],
      "type": "string",
      "readOnly": true,
      "description": "The status of the external payroll. The status will be `unprocessed` when the external payroll is created and transition to `processed` once tax liabilities are entered and finalized.  Once in the `processed` status all actions that can edit an external payroll will be disabled."
    },
    "check_date": {
      "type": "string",
      "readOnly": true,
      "description": "External payroll's check date."
    },
    "company_uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the company."
    },
    "payment_period_end_date": {
      "type": "string",
      "readOnly": true,
      "description": "External payroll's pay period end date."
    },
    "payment_period_start_date": {
      "type": "string",
      "readOnly": true,
      "description": "External payroll's pay period start date."
    }
  },
  "x-examples": {
    "Example": {
      "uuid": "c5fdae57-5483-4529-9aae-f0edceed92d4",
      "check_date": "2022-06-03",
      "company_uuid": "bcb305b0-2855-4025-8d22-e484a9e6b7c9",
      "payment_period_end_date": "2022-05-30",
      "payment_period_start_date": "2022-05-15"
    }
  },
  "description": "The representation of an external payroll with minimal information."
}

{
  "type": "object",
  "title": "",
  "x-tags": [
    "External Payrolls"
  ],
  "properties": {
    "employee_uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the employee."
    },
    "tax_suggestions": {
      "type": "object",
      "readOnly": true,
      "properties": {
        "amount": {
          "type": "string",
          "readOnly": true,
          "description": "Calculated tax amount."
        },
        "tax_id": {
          "type": "integer",
          "readOnly": true,
          "description": "The ID of the tax."
        }
      },
      "description": "Possible tax liabilities selections."
    }
  },
  "x-examples": {
    "Example": {
      "employee_uuid": "d21848d5-446f-48a8-9430-30fbefeabda4",
      "tax_suggestions": [
        {
          "amount": 500,
          "tax_id": 1
        },
        {
          "amount": 100,
          "tax_id": 2
        },
        {
          "amount": 30,
          "tax_id": 4
        }
      ]
    }
  },
  "description": "The representation of an external payroll with minimal information."
}

{
  "type": "object",
  "required": [
    "check_date",
    "payment_period_start_date",
    "payment_period_end_date"
  ],
  "properties": {
    "check_date": {
      "type": "string",
      "description": "External payroll's check date."
    },
    "payment_period_end_date": {
      "type": "string",
      "description": "External payroll's pay period end date."
    },
    "payment_period_start_date": {
      "type": "string",
      "description": "External payroll's pay period start date."
    }
  },
  "description": ""
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Tax-Liabilities-Selections"
  }
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/External-Payroll-Tax-Suggestions"
  }
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/External-Payroll-Basic"
  }
}

{
  "type": "object",
  "properties": {
    "replace_fields": {
      "type": "boolean",
      "description": "Patch update external payroll items when set to true, otherwise it will overwrite the previous changes."
    },
    "external_payroll_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "taxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "amount": {
                  "type": "string",
                  "description": "The amount of the tax."
                },
                "tax_id": {
                  "type": "integer",
                  "description": "The ID of the tax."
                }
              }
            },
            "description": "An array of taxes for the employee. Depends on your company selections, taxes include federal income tax, social security, medicare, and more."
          },
          "benefits": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "benefit_id": {
                  "type": "integer",
                  "description": "The ID of the benefit."
                },
                "employee_deduction_amount": {
                  "type": "string",
                  "description": "Employee deduction amount towards the benefit"
                },
                "company_contribution_amount": {
                  "type": "string",
                  "description": "Company contribution amount towards the benefit"
                }
              },
              "description": "An array of benefits for the employee. Depends on your company selections, benefits include 401k, health insurance and more."
            }
          },
          "earnings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "hours": {
                  "type": "string",
                  "description": "The hour of the compensation for the pay period."
                },
                "amount": {
                  "type": "string",
                  "description": "The amount of the earning."
                },
                "earning_id": {
                  "type": "integer",
                  "description": "The ID of the earning."
                },
                "earning_type": {
                  "enum": [
                    "CompanyPayType",
                    "CompanyEarningType"
                  ],
                  "type": "string",
                  "description": "The earning type for the compensation."
                }
              },
              "description": "An array of earnings for the employee. Depends on your company selections, earnings includes wages, hours, bonuses, tips, commission and more."
            }
          },
          "employee_uuid": {
            "type": "string",
            "description": "The UUID of the employee."
          }
        },
        "description": "Submit wages, benefits, taxes for each employee"
      }
    }
  }
}

{
  "type": "object",
  "properties": {
    "liability_selections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tax_id": {
            "type": "integer",
            "description": "The ID of the tax."
          },
          "unpaid_liability_amount": {
            "type": "number",
            "description": "A selection of unpaid liability amount."
          },
          "last_unpaid_external_payroll_uuid": {
            "type": "string",
            "nullable": true,
            "description": "The UUID of the last unpaid external payroll uuid. It should be null when the full amount of tax liability has been paid."
          }
        },
        "description": ""
      }
    }
  }
}

{
  "type": "object",
  "title": "Federal-Tax-Details",
  "x-tags": [
    "Federal Tax Details"
  ],
  "properties": {
    "has_ein": {
      "type": "boolean",
      "description": "Whether company's Employer Identification Number (EIN) is present"
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field."
    },
    "legal_name": {
      "type": "string",
      "description": "The legal name of the company"
    },
    "filing_form": {
      "type": "string",
      "description": "The form used by the company for federal tax filing. One of:\n- 941 (Quarterly federal tax return form)\n- 944 (Annual federal tax return form)"
    },
    "ein_verified": {
      "type": "boolean",
      "description": "Whether the EIN was able to be verified as a valid EIN with the IRS. "
    },
    "tax_payer_type": {
      "type": "string",
      "description": "What type of tax entity the company is. One of:\n- C-Corporation\n- S-Corporation\n- Sole proprietor\n- LLC\n- LLP\n- Limited partnership\n- Co-ownership\n- Association\n- Trusteeship\n- General partnership\n- Joint venture\n- Non-Profit"
    },
    "taxable_as_scorp": {
      "type": "boolean",
      "description": "Whether the company is taxed as an S-Corporation. Tax payer types that may be taxed as an S-Corporation include:\n- S-Corporation\n- C-Corporation\n- LLC"
    }
  },
  "x-examples": {
    "Example": {
      "value": {
        "has_ein": true,
        "version": "string",
        "legal_name": "string",
        "filing_form": "string",
        "ein_verified": true,
        "tax_payer_type": "string",
        "taxable_as_scorp": false
      }
    }
  }
}

{
  "type": "object",
  "required": [
    "version"
  ],
  "properties": {
    "ein": {
      "type": "string",
      "description": "The EIN of of the company"
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field."
    },
    "legal_name": {
      "type": "string",
      "description": "The legal name of the company"
    },
    "filing_form": {
      "type": "string",
      "description": "The form used by the company for federal tax filing. One of:\n- 941 (Quarterly federal tax return)\n- 944 (Annual federal tax return)"
    },
    "tax_payer_type": {
      "enum": [
        "C-Corporation",
        "S-Corporation",
        "Sole proprietor",
        "LLC",
        "LLP",
        "Limited partnership",
        "Co-ownership",
        "Association",
        "Trusteeship",
        "General partnership",
        "Joint venture",
        "Non-Profit"
      ],
      "type": "string",
      "description": "What type of tax entity the company is"
    },
    "taxable_as_scorp": {
      "type": "boolean",
      "description": "Whether this company should be taxed as an S-Corporation"
    }
  }
}

{
  "type": "object",
  "title": "Flow",
  "x-tags": [
    "Flows"
  ],
  "properties": {
    "url": {
      "type": "string"
    },
    "expires_at": {
      "type": "string"
    }
  },
  "x-examples": {
    "Example": {
      "url": "https://flows.gusto-demo.com/flows/lO2BHHAMCScPVV9G5WEURW0Im_nP9mGYloQgjUWbenQ",
      "expires_at": "2021-12-28 04:25:48"
    }
  },
  "description": "The representation of a flow in Gusto white-label UI."
}

{
  "type": "object",
  "required": [
    "flow_type"
  ],
  "properties": {
    "flow_type": {
      "type": "string",
      "description": "flow type"
    },
    "entity_type": {
      "enum": [
        "Company",
        "Employee"
      ],
      "type": "string",
      "description": "the type of target entity applicable to the flow. This field is optional for company flows, please refer to the flow_types table above for more details."
    },
    "entity_uuid": {
      "type": "string",
      "description": "UUID of the target entity applicable to the flow. This field is optional for company flows, please refer to the flow_types table above for more details."
    }
  }
}

{
  "enum": [
    "Exempt",
    "Salaried Nonexempt",
    "Nonexempt",
    "Owner",
    "Commission Only Exempt",
    "Commission Only Nonexempt"
  ],
  "type": "string",
  "description": "The FLSA status for this compensation. Salaried ('Exempt') employees are paid a fixed salary every pay period. Salaried with overtime ('Salaried Nonexempt') employees are paid a fixed salary every pay period, and receive overtime pay when applicable. Hourly ('Nonexempt') employees are paid for the hours they work, and receive overtime pay when applicable. Commissioned employees ('Commission Only Exempt') earn wages based only on commission. Commissioned with overtime ('Commission Only Nonexempt') earn wages based on commission, and receive overtime pay when applicable. Owners ('Owner') are employees that own at least twenty percent of the company. "
}

{
  "type": "object",
  "title": "Form",
  "x-tags": [
    "Forms"
  ],
  "properties": {
    "name": {
      "type": "string",
      "readOnly": true,
      "description": "The type identifier of the form"
    },
    "uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the form"
    },
    "year": {
      "type": "integer",
      "nullable": true,
      "readOnly": true,
      "description": "The year of this form. For some forms, e.g. tax forms, this is the year which the form represents. A W2 for January - December 2022 would be delivered in January 2023 and have a year value of 2022. This value is nullable and will not be present on all forms."
    },
    "draft": {
      "type": "boolean",
      "readOnly": true,
      "description": "If the form is in a draft state. E.g. End of year tax forms may be provided in a draft state prior to being finalized."
    },
    "title": {
      "type": "string",
      "readOnly": true,
      "description": "The title of the form"
    },
    "quarter": {
      "type": "integer",
      "nullable": true,
      "readOnly": true,
      "description": "The quarter of this form. For some forms, e.g. tax forms, this is the calendar quarter which this form represents. An Employer's Quarterly Federal Tax Return (Form 941) for April, May, June 2022 would have a quarter value of 2 (and a year value of 2022). This value is nullable and will not be present on all forms."
    },
    "description": {
      "type": "string",
      "readOnly": true,
      "description": "The description of the form"
    },
    "requires_signing": {
      "type": "boolean",
      "readOnly": true,
      "description": "A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed."
    }
  },
  "x-examples": {
    "Example": {
      "name": "company_direct_deposit",
      "uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
      "title": "Direct Deposit Authorization",
      "description": "We need you to sign paperwork to authorize us to debit and credit your bank account and file and pay your taxes.",
      "requires_signing": true
    }
  }
}

{
  "type": "object",
  "title": "Form Pdf",
  "properties": {
    "uuid": {
      "type": "string",
      "readOnly": true,
      "description": "the UUID of the form"
    },
    "document_url": {
      "type": "string",
      "description": "the URL of the form"
    }
  }
}

{
  "type": "object",
  "title": "Form",
  "x-tags": [
    "Forms"
  ],
  "properties": {
    "name": {
      "type": "string",
      "readOnly": true,
      "description": "The type identifier of the form"
    },
    "uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the form"
    },
    "year": {
      "type": "integer",
      "nullable": true,
      "readOnly": true,
      "description": "The year of this form. For some forms, e.g. tax forms, this is the year which the form represents. A 1099 for January - December 2022 would be delivered in January 2023 and have a year value of 2022. This value is nullable and will not be present on all forms."
    },
    "draft": {
      "type": "boolean",
      "readOnly": true,
      "description": "If the form is in a draft state. E.g. End of year tax forms may be provided in a draft state prior to being finalized."
    },
    "title": {
      "type": "string",
      "readOnly": true,
      "description": "The title of the form"
    },
    "quarter": {
      "type": "integer",
      "nullable": true,
      "readOnly": true,
      "description": "The quarter of this form. This value is currently always null since it is not present on any contractor forms."
    },
    "description": {
      "type": "string",
      "readOnly": true,
      "description": "The description of the form"
    },
    "contractor_uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The contractor UUID"
    },
    "requires_signing": {
      "type": "boolean",
      "readOnly": true,
      "description": "A boolean flag that indicates whether the form needs signing or not. Note that this value will change after the form is signed."
    }
  },
  "x-examples": {
    "Example": {
      "name": "US_1099",
      "uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
      "year": 2020,
      "draft": false,
      "title": "Form 1099: 2020",
      "quarter": null,
      "description": "Form 1099 records your annual income as a contractor.",
      "contractor_uuid": "123dd616-6dbc-4724-938a-403f6217a933",
      "requires_signing": false
    }
  }
}

{
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "readOnly": true,
      "description": "The UUID of the garnishment in Gusto."
    },
    "times": {
      "type": "integer",
      "default": null,
      "nullable": true,
      "readOnly": false,
      "description": "The number of times to apply the garnishment. Ignored if recurring is true."
    },
    "active": {
      "type": "boolean",
      "default": true,
      "description": "Whether or not this garnishment is currently active."
    },
    "amount": {
      "type": "string",
      "format": "float",
      "readOnly": false,
      "description": "The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. \"8.00\"."
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/idempotency) for information on how to use this field."
    },
    "recurring": {
      "type": "boolean",
      "default": false,
      "readOnly": false,
      "description": "Whether the garnishment should recur indefinitely."
    },
    "description": {
      "type": "string",
      "readOnly": false,
      "description": "The description of the garnishment."
    },
    "court_ordered": {
      "type": "boolean",
      "readOnly": false,
      "description": "Whether the garnishment is court ordered."
    },
    "employee_uuid": {
      "type": "integer",
      "readOnly": true,
      "description": "The UUID of the employee to which this garnishment belongs."
    },
    "annual_maximum": {
      "type": "string",
      "format": "float",
      "default": null,
      "nullable": true,
      "readOnly": false,
      "description": "The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\"."
    },
    "pay_period_maximum": {
      "type": "string",
      "format": "float",
      "default": null,
      "nullable": true,
      "description": "The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. \"16.00\"."
    },
    "deduct_as_percentage": {
      "type": "boolean",
      "default": false,
      "readOnly": false,
      "description": "Whether the amount should be treated as a percentage to be deducted per pay period."
    }
  },
  "x-examples": {
    "Example": {
      "uuid": "4c7841a2-1363-497e-bc0f-664703c7484f",
      "times": 5,
      "active": true,
      "amount": "8.00",
      "version": "52b7c567242cb7452e89ba2bc02cb476",
      "recurring": false,
      "description": "Company loan to employee",
      "court_ordered": false,
      "employee_uuid": "a6b53294-f871-4db2-bbd4-8c3d1fe56440",
      "annual_maximum": null,
      "pay_period_maximum": "100.00",
      "deduct_as_percentage": true
    }
  },
  "description": "Garnishments, or employee deductions, are fixed amounts or percentages deducted from an employee’s pay. They can be deducted a specific number of times or on a recurring basis. Garnishments can also have maximum deductions on a yearly or per-pay-period bases. Common uses for garnishments are court-ordered payments for child support or back taxes. Some companies provide loans to their employees that are repaid via garnishments."
}

{
  "type": "object",
  "required": [
    "amount",
    "description",
    "court_ordered"
  ],
  "properties": {
    "times": {
      "type": "integer",
      "default": null,
      "nullable": true,
      "readOnly": false,
      "description": "The number of times to apply the garnishment. Ignored if recurring is true."
    },
    "active": {
      "type": "boolean",
      "default": true,
      "description": "Whether or not this garnishment is currently active."
    },
    "amount": {
      "type": "string",
      "format": "float",
      "readOnly": false,
      "description": "The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. \"8.00\"."
    },
    "recurring": {
      "type": "boolean",
      "default": false,
      "readOnly": false,
      "description": "Whether the garnishment should recur indefinitely."
    },
    "description": {
      "type": "string",
      "readOnly": false,
      "description": "The description of the garnishment."
    },
    "court_ordered": {
      "type": "boolean",
      "readOnly": false,
      "description": "Whether the garnishment is court ordered."
    },
    "annual_maximum": {
      "type": "string",
      "format": "float",
      "default": null,
      "nullable": true,
      "readOnly": false,
      "description": "The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\"."
    },
    "pay_period_maximum": {
      "type": "string",
      "format": "float",
      "default": null,
      "nullable": true,
      "description": "The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. \"16.00\"."
    },
    "deduct_as_percentage": {
      "type": "boolean",
      "default": false,
      "readOnly": false,
      "description": "Whether the amount should be treated as a percentage to be deducted per pay period."
    }
  },
  "description": ""
}

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Garnishment"
  }
}

{
  "type": "object",
  "required": [
    "version"
  ],
  "properties": {
    "times": {
      "type": "integer",
      "default": null,
      "nullable": true,
      "readOnly": false,
      "description": "The number of times to apply the garnishment. Ignored if recurring is true."
    },
    "active": {
      "type": "boolean",
      "default": true,
      "description": "Whether or not this garnishment is currently active."
    },
    "amount": {
      "type": "string",
      "format": "float",
      "readOnly": false,
      "description": "The amount of the garnishment. Either a percentage or a fixed dollar amount. Represented as a float, e.g. \"8.00\"."
    },
    "version": {
      "type": "string",
      "description": "The current version of the object. See the [versioning guide](https://docs.gusto.com/embedded-payroll/docs/versioning#object-layer) for information on how to use this field."
    },
    "recurring": {
      "type": "boolean",
      "default": false,
      "readOnly": false,
      "description": "Whether the garnishment should recur indefinitely."
    },
    "description": {
      "type": "string",
      "readOnly": false,
      "description": "The description of the garnishment."
    },
    "court_ordered": {
      "type": "boolean",
      "readOnly": false,
      "description": "Whether the garnishment is court ordered."
    },
    "annual_maximum": {
      "type": "string",
      "format": "float",
      "default": null,
      "nullable": true,
      "readOnly": false,
      "description": "The maximum deduction per annum. A null value indicates no maximum. Represented as a float, e.g. \"200.00\"."
    },
    "pay_period_maximum": {
      "type": "string",
      "format": "float",
      "default": null,
      "nullable": true,
      "description": "The maximum deduction per pay period. A null value indicates no maximum. Represented as a float, e.g. \"16.00\"."
    },
    "deduct_as_percentage": {
      "type": "boolean",
      "default": false,
      "readOnly": false,
      "description": "Whether the amount should be treated as a percentage to be deducted per pay period."
    }
  }
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Current status of the Generated Document"
    },
    "request_uuid": {
      "type": "string",
      "description": "A unique identifier of the Generated Document request"
    },
    "document_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The array of urls to access the documents."
    }
  },
  "x-examples": {
    "example-1": {
      "status": "succeeded",
      "request_uuid": "p83d0ca8-7d41-42a9-834y-7d218ef6cb20",
      "document_urls": [
        "https://document.url.com"
      ]
    }
  }
}