Penfold Partner API
POST /employers/{employerId}/contributions
Bearer auth

Create multiple contributions for a specified employer in a single request. Contributions are processed asynchronously — the response returns an upload ID that can be used to track processing status via the Uploads endpoints.

Path parameters

  • employerId string(uuid) Required

    Penfold employer UUID

application/json

Body Required

  • employeeId string Required

    Identifier for the employee associated with the contribution.

  • employerContributionsAmount number Required

    The amount of the employer's contribution for the given pay period.

  • employeeContributionsAmount number Required

    The amount of the employee's contribution for the given pay period.

  • payPeriodStartDate string(date) Required

    The start date of the pay period, in YYYY-MM-DD format.

  • payPeriodEndDate string(date) Required

    The end date of the pay period, in YYYY-MM-DD format.

Responses

  • 201 application/json

    Submission accepted for processing.

    Hide response attributes Show response attributes object
    • id string Required

      Upload ID for tracking the submission. Use the Uploads endpoints to check processing status.

    • status string Required

      Initial status of the submission.

      Values are ReceivedFile or Processing.

    • createdAt string(date-time) Required

      When the submission was created (ISO 8601).
  • 400 application/json

    Request body failed validation

    Hide response attributes Show response attributes object
    • error string Required

      A descriptive error message.

    • validationErrors array[object]
      Hide validationErrors attributes Show validationErrors attributes object
      • field string Required

        The name of the field that failed validation.

      • message string Required

        A descriptive error message.
  • 401 application/json

    Missing or invalid authentication token

    Hide response attribute Show response attribute object
    • error string Required
  • 404 application/json

    Resource not found

    Hide response attribute Show response attribute object
    • error string Required
  • 500 application/json

    Internal server error

    Hide response attribute Show response attribute object
    • error string Required
POST /employers/{employerId}/contributions 
curl \
 --request POST 'https://partner-api.getpenfold.com/v1/employers/{employerId}/contributions' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '[{"employeeId":"e9876-wxyz-4321-stuv","employerContributionsAmount":1200.0,"employeeContributionsAmount":300.0,"payPeriodStartDate":"2023-03-01","payPeriodEndDate":"2023-03-15"}]'
Request examples 
[
  {
    "employeeId": "e9876-wxyz-4321-stuv",
    "employerContributionsAmount": 1200.0,
    "employeeContributionsAmount": 300.0,
    "payPeriodStartDate": "2023-03-01",
    "payPeriodEndDate": "2023-03-15"
  }
]
Response examples (201) 
{
  "id": "u1234-abcd-5678-efgh",
  "status": "ReceivedFile",
  "createdAt": "2023-03-01T12:00:00Z"
}
Response examples (400) 
{
  "error": "validation failed",
  "validationErrors": [
    {
      "field": "companyNumber",
      "message": "companyNumber is required"
    },
    {
      "field": "primaryContactEmail",
      "message": "must be a valid email address"
    }
  ]
}
Response examples (401) 
{
  "error": "unauthorized"
}
Response examples (404) 
{
  "error": "not found"
}
Response examples (500) 
{
  "error": "internal server error"
}