Filing

Partner-visible state for one ordinary FPS Filing. The valid status and action combinations are:

status Meaning Valid requiredAction
pending PayrollKit created the Filing but has no evidence that it was sent. It is being prepared or a known pre-send problem has stopped progress. wait or contact_support
processing A send may have happened and PayrollKit can safely continue the same HMRC submission conversation. This is not acceptance. wait
accepted A saved final HMRC response established that HMRC accepted the FPS. none
rejected A saved final HMRC response established that HMRC rejected the FPS. Approved payroll remains unchanged. contact_support
result_unknown The FPS may have reached HMRC, but PayrollKit has not established a final result. Another FPS must not be submitted while PayrollKit investigates or support reconciles the outcome. wait or contact_support
  • coveredEmploymentCalculationIds
    Type: array of string 1…
    min length:  
    1
    max length:  
    200
    required

    Employment Calculations reported by this Filing. A Pay Run with no reportable Employment Calculations creates no Filing.

  • createdAt
    Type: stringFormat: date-time
    required

    When PayrollKit created the Filing.

  • id
    Type: string
    min length:  
    1
    max length:  
    200
    required

    PayrollKit Filing ID.

  • issues
    Type: array of object
    required

    Always present. Empty when there is no issue. Each issue explains what is blocked and includes a clear nextAction; contact_support responses contain at least one issue.

    Properties: 9
  • payRunId
    Type: string
    min length:  
    1
    max length:  
    200
    required

    PayrollKit ID of the approved Pay Run reported by this Filing.

  • reportedPaymentDate
    Type: stringFormat: date
    required

    Payment date reported in the FPS.

  • requiredAction
    Type: "none" or "wait" or "contact_support"enum
    required

    What the integration should do next. none means no action is required, wait means monitor the Filing without submitting an FPS, and contact_support means stop automated action and contact PayrollKit support.

  • resolvedAt
    Type: string | nullFormat: date-time
    required

    When PayrollKit saved the final HMRC response that established acceptance or rejection, or null before a final result is known.

  • status
    Type: stringenum
    required

    Latest Partner-visible lifecycle status. See the Filing status table above.

    values
    pendingprocessingacceptedrejectedresult_unknown
  • taxPeriod
    Type: string
    required

    Tax month or week containing the reported payment date.

  • taxYear
    Type: string
    required
  • type
    const:  
    fps
    required

    Filing type. Only ordinary FPS Filings are supported in v1.

  • updatedAt
    Type: stringFormat: date-time
    required

    When the Filing status, required action or issues last changed.