Create an agreement signing session.

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.getpenfold.dev/mcp

Standard setup for AI tools providing an mcp.json file

      
          mcp.json

"Penfold Partner API MCP server": {
  "url": "https://docs.getpenfold.dev/mcp"
}

POST /employers/{employer_id}/agreement-signing-sessions

O auth2 client credentials

Create an agreement signing session for an employer. Returns a redirect_url containing a short-lived, one-time token that you open in the employer admin's browser to complete regulated agreement steps on Penfold's platform.

Path parameters

employer_id string Required

application/json

Body Required

object

Create an agreement signing session for an employer. Returns a redirect_url containing a short-lived, one-time token that you open in the employer admin's browser to complete regulated agreement steps on Penfold's platform.

Responses

201 application/json

Signing session created successfully.
Hide response attributes Show response attributes object
- signing_session_id string Required
  
  Correlates this attempt across redirect, webhook, and support.
- redirect_url string Required
  
  Full URL to send the user to. Contains a Penfold-issued short-lived, one-time token. Do not construct or modify this URL.
- expires_at string(date-time) Required
  
  ISO 8601 instant after which the session and redirect_url are invalid. Sessions expire 15 minutes after creation unless otherwise stated.
400 application/json

Bad request, the request is malformed or contains invalid data.
Hide response attributes Show response attributes object
- error string
  
  A descriptive error message.
- validation_errors array[object]
  
  Hide validation_errors attributes Show validation_errors attributes object
  
  field string Required
  
  The name of the field that failed validation.
  
  message string Required
  
  A descriptive error message.
404 application/json

Resource not found.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
409 application/json

Conflict — a new signing session cannot be created. This occurs when the employer has already completed agreement signing, or when the employer's status is not PendingPa (not eligible to start signing).
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
500 application/json

Internal server error
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.

POST /employers/{employer_id}/agreement-signing-sessions

curl \
 --request POST 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/agreement-signing-sessions' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json"

Request examples

{}

Response examples (201)

{
  "signing_session_id": "cl9gujidl001o9ksfnrgr8zq1",
  "redirect_url": "https://platform.getpenfold.com/partner/sign-agreement?token=eyJhbGciOiJIUzI1NiJ9...",
  "expires_at": "2026-05-06T10:35:00Z"
}

Response examples (400)

{
  "error": "Bad request: invalid data provided.",
  "validation_errors": [
    {
      "field": "email",
      "message": "Email address is invalid."
    }
  ]
}

Response examples (404)

{
  "error": "Bad request: invalid data provided."
}

Response examples (409)

{
  "error": "employer has already signed"
}

{
  "error": "employer is not eligible for agreement signing - status is not 'PendingPa'"
}

Response examples (500)

{
  "error": "Bad request: invalid data provided."
}