# Create signing session

**POST /employers/{employerId}/agreement-signing-sessions**

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.



## Servers
- Production: https://partner-api.getpenfold.com/v4 (Production)
- Staging: https://partner-api.getpenfold.dev/v4 (Staging)


## Authentication methods
- Bearer auth


## Parameters
### 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))
  Penfold employer UUID



### Body: application/json (object)

- **returnUrl** (string(uri))
  Where Penfold redirects the browser after the signing journey.
  Must be a pre-registered HTTPS URL for your integration.

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



## Responses
### 201
Signing session created successfully.

#### Body: application/json (object)
- **signingSessionId** (string)
  Correlates this attempt across redirect, webhook, and support.

- **redirectUrl** (string(uri))
  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))
  ISO 8601 instant after which the session and redirectUrl are invalid.
  Sessions expire 15 minutes after creation unless otherwise stated.


### 400
Request body failed validation

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.

- **validationErrors** (array[object])


### 401
Missing or invalid authentication token

#### Body: application/json (object)
- **error** (string)


### 404
Resource not found

#### Body: application/json (object)
- **error** (string)


### 500
Internal server error

#### Body: application/json (object)
- **error** (string)



[Powered by Bump.sh](https://bump.sh)