### Actuarial Certificate — Class-to-Provider Requests

The Actuarial Certificate integration is bi-directional. While the [API Reference](/products/class/apis/actuarial-provider/actuarial-certificate) documents the callback endpoints your system POSTs to on Class, this page documents the request that **Class POSTs to your endpoint** when a user requests a certificate.
You must host an HTTPS endpoint (registered with Class) that accepts this request and returns an acknowledgement.

#### The request payload

When a user requests a certificate, Class POSTs the fund data to your registered endpoint. The payload conforms to the **Actuarial Certificate Request Data Standard (v1.0)**.
The standard is the source of truth for the payload structure, field definitions, and enumerations. Refer to:

- **Standard overview & schema:** [https://accurium.github.io/actcertstd/ea-diagram](https://accurium.github.io/actcertstd/ea-diagram)
- **Worked examples with sample data:**
  - Deemed segregation: [https://accurium.github.io/actcertstd/example1-deemed-seg](https://accurium.github.io/actcertstd/example1-deemed-seg)
  - Elected segregation: [https://accurium.github.io/actcertstd/example2-elected-seg](https://accurium.github.io/actcertstd/example2-elected-seg)


Class sends the request as **XML by default**. The format (XML or JSON) is agreed per provider during onboarding; Class sets the `Content-Type` and `Accept` headers to match your configured format. Your endpoint parses this payload and returns an acknowledgement.

#### The acknowledgement you return

Your endpoint must respond synchronously. Return a `Response` object to accept the request, or a `ResponseStatus` object to reject it — the two cases are documented separately below.

#### Acknowledgement — successful response

Return a `Response` containing the response URL and, optionally, a draft percentage:

| Field | Required | What Class does with it |
|  --- | --- | --- |
| `Response.Url` | **Yes** | The response URL. Class surfaces this link to the requesting user so they can review the ECPI% and finalise. An empty or missing URL fails the request. |
| `Response.Percentage` | No | An optional draft ECPI% as a decimal. If supplied, Class records it as the initial (interim) percentage; you can post the final value later via the callback endpoints. To omit it, leave the field out entirely — do not send `0`, which would record a 0% interim. |


**JSON**

```json
{
    "Response": {
        "Url": "https://your-service.example/certificate/review?ref=8f3a2b...",
        "Percentage": 63.18
    }
}
```

**XML**

```xml
<ActuarialCertificateResponseInfo>
    <Response>
        <Url>https://your-service.example/certificate/review?ref=8f3a2b...</Url>
        <Percentage>63.18</Percentage>
    </Response>
</ActuarialCertificateResponseInfo>
```

#### Acknowledgement — error response

To reject a request, populate the `ResponseStatus` error fields. Class treats a response as errored if either field contains a message. Ideally, populate **both** fields:

| Field | What Class does with it |
|  --- | --- |
| `DisplayError` | A user-facing message. Class surfaces this to the requesting user so they understand why the request failed. |
| `Error` | Technical detail for Class's internal diagnostics. Logged internally and not shown to the user. |


Populate `DisplayError` with a clear, user-friendly message and `Error` with any technical detail that will help Class troubleshoot. Each field is a list, so you can supply more than one message:

**JSON**

```json
{
    "ResponseStatus": {
        "DisplayError": [
            "We could not process this fund because the member details are incomplete. Please review and resubmit."
        ],
        "Error": [
            "Validation failed: Member[2].DateOfBirth is null; unable to compute ECPI."
        ]
    }
}
```

**XML**

```xml
<ActuarialCertificateResponseInfo>
    <ResponseStatus>
        <DisplayError>We could not process this fund because the member details are incomplete. Please review and resubmit.</DisplayError>
        <Error>Validation failed: Member[2].DateOfBirth is null; unable to compute ECPI.</Error>
    </ResponseStatus>
</ActuarialCertificateResponseInfo>
```

#### The response URL

The response URL is **provider-owned** — Class does not generate it or enforce a format. Class validates only that it is non-empty, stores it, and surfaces it to the requesting user so they can review and finalise.

#### Parameter mapping

The identifiers you'll need for the callback endpoints are taken from the initial request payload:

| Callback parameter | Payload mapping |
|  --- | --- |
| `BusinessCode` | `Client.SourceRef` |
| `FundCode` | `Fund.SourceRef` |
| `RequestId` | `SourceRef` (root of the payload) |


#### What your system should do

- Authenticate the caller if required (mechanism agreed during onboarding).
- Persist the `RequestId`, `BusinessCode`, `FundCode`, and financial year — you'll need these for the callbacks.
- Calculate (or begin calculating) the ECPI%.
- Return a response URL for the Class user to review and finalise.
- Once finalised, call back to Class to create a status, optionally update it, and upload the certificate PDF — see [Provider-to-Class Updates](/products/class/apis/actuarial-provider/provider-to-class).


#### Related

- **Callback endpoints your system POSTs to Class** — see the [API Reference](/products/class/apis/actuarial-provider/actuarial-certificate).
- **The status lifecycle** — see [Workflow](/products/class/apis/actuarial-provider/workflow).
- **How to obtain a bearer token** — see [Authentication](/products/class/apis/actuarial-provider/authentication).