Retrieve 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"
}

GET /employers/{employer_id}/agreement-signing-sessions/{signing_session_id}

O auth2 client credentials

Fetch the current state of a initiated agreement signing session for an employer. Intended for polling — you can call this to determine whether an employer has completed the signing flow.

Path parameters

employer_id string Required
signing_session_id string Required

Responses

200 application/json

Signing session retrieved successfully.
Hide response attributes Show response attributes object
- id string Required
  
  The unique identifier for the signing session.
- return_url string Required
  
  The URL the employer is redirected to once the signing session reaches a terminal state.
- expires_at string(date-time) Required
  
  The date and time the signing session expires, in ISO 8601 format. Sessions that pass this time without reaching a terminal state are treated as Failed with failure_code SessionExpired.
- result string | null Required
  
  The current state of the signing session. Possible values:
  
  Open: the session has been created but not yet acted on by the employer.
  
  Success: the employer accepted the agreement.
  
  Cancelled: the employer cancelled the signing flow.
  
  Failed: the session reached a terminal failure state. See failure_code for the specific reason.
  
  May be null if the session has not yet been initialised.
  
  Values are Open, Success, Cancelled, or Failed.
- failure_code string
  
  The reason a session reached a Failed state. null unless result is Failed.
  
  Values are SessionExpired, CompletionFailed, or CancellationFailed.
- completed_at string(date-time) | null
  
  The date and time the session reached a terminal state (Success or Cancelled). null if the session is still Open or Failed.
401 application/json

Unauthorized, the request requires authentication, and the provided credentials are either missing or incorrect.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
404 application/json

Signing session not found. The specified signing_session_id does not match an existing session for this employer and organisation.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
405 application/json

Method not allowed
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.

GET /employers/{employer_id}/agreement-signing-sessions/{signing_session_id}

curl \
 --request GET 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/agreement-signing-sessions/{signing_session_id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Response examples (200)

{
  "id": "ckljutchi4gnv088634058909",
  "return_url": "https://partner.example.com/penfold/return",
  "expires_at": "2026-05-22T12:30:00Z",
  "result": "Open",
  "failure_code": "SessionExpired",
  "completed_at": "2026-05-22T12:15:00Z"
}

Response examples (401)

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

Response examples (404)

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

Response examples (405)

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