Create 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/{employerId}/agreement-signing-sessions

Bearer auth

Create an agreement signing session for an employer. Returns a redirectUrl 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.

Idempotency

Include an Idempotency-Key header (e.g. a UUID) per logical "create session" attempt. Reusing the same key within 24 hours for the same employer returns the same signingSessionId and redirectUrl if the session is still valid.

Redirect flow

After the user completes, cancels, or fails, Penfold redirects the browser back to your returnUrl with query parameters:

{returnUrl}?state={state}&signingSessionId={signingSessionId}&result={result}

When result is failed, Penfold appends failureCode:

{returnUrl}?...&result=failed&failureCode={failureCode}

Parameter	Presence	Description
`state`	Always	Echo of the `state` you sent. Reject if it does not match.
`signingSessionId`	Always	Same id as in the create-session response.
`result`	Always	Terminal outcome: `success`, `cancelled`, or `failed`.
`failureCode`	Only when `result` is `failed`	Machine-readable reason. Omitted otherwise.

Important: Treat the redirect as provisional UX only — the authoritative outcome is delivered via the EmployerAgreementSigningCompleted webhook. If webhooks are delayed, poll GET /employers/{employerId} until employer status reflects agreement completion.

Headers

Idempotency-Key string

Opaque value (e.g. UUID) per logical create-session attempt. Reusing the same key within 24 hours for the same employer returns the original session if still valid.

Path parameters

employerId string(uuid) Required

Penfold employer UUID

application/json

Body Required

returnUrl string(uri) Required

Where Penfold redirects the browser after the signing journey. Must be a pre-registered HTTPS URL for your integration.
state string Required

Opaque value you generate (CSRF / correlation). Penfold echoes it on redirect unchanged.

Minimum length is 1, maximum length is 256.

Responses

201 application/json

Signing session created successfully.
Hide response attributes Show response attributes object
- signingSessionId string Required
  
  Correlates this attempt across redirect, webhook, and support.
- redirectUrl string(uri) Required
  
  Full URL to send the user to. Contains a Penfold-issued short-lived, one-time token. Do not construct or modify this URL.
- expiresAt string(date-time) Required
  
  ISO 8601 instant after which the session and redirectUrl are invalid. Sessions expire 15 minutes after creation unless otherwise stated.
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}/agreement-signing-sessions

curl \
 --request POST 'https://partner-api.getpenfold.com/v4/employers/{employerId}/agreement-signing-sessions' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "Idempotency-Key: string" \
 --data '{"returnUrl":"https://partner.example.com/integrations/penfold/callback","state":"c2d79b5c-bf4d-4e4a-94ec-5be8e7d6f2e9"}'

Request example

{
  "returnUrl": "https://partner.example.com/integrations/penfold/callback",
  "state": "c2d79b5c-bf4d-4e4a-94ec-5be8e7d6f2e9"
}

Response examples (201)

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

Response examples (400)

{
  "error": "validation failed",
  "validationErrors": [
    {
      "field": "returnUrl",
      "message": "must be a pre-registered HTTPS URL"
    },
    {
      "field": "state",
      "message": "length must be between 1 and 256 characters"
    }
  ]
}

Response examples (401)

{
  "error": "unauthorized"
}

Response examples (404)

{
  "error": "not found"
}

Response examples (500)

{
  "error": "internal server error"
}