# Attach a Document

Source: https://docs.pitchpointsolutions.com/api/session/put_session_attachment/

**Beta**

Stores a signed authorization or an identity document in the session, so you can start a workflow for a product that needs one: an SSA-89, an IRS 8821 or 4506-T, a verification of employment authorization, or the photo identification an 8821 carries alongside its form.

You name the document, say whom on the loan it belongs to, and optionally say what it states, such as the signature type of an SSA-89. A workflow started for that person finds the document itself.

> **Before Starting:** Stage the loan first. A document belongs to a person, company or employer on the staged loan, so a session with nothing staged has nobody to attach it to. See [Stage Data](https://docs.pitchpointsolutions.com/api/session/stage_session_sami/).

### Sample

The document travels base64-encoded inside the JSON body. This sample builds the body from a PDF on disk with `jq`, then sends it.

```bash
url="https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001/attachments/ecbsv-b1"
base64 < ssa89-jane.pdf | tr -d '\n' > ssa89-jane.b64
jq -n --rawfile document ssa89-jane.b64 '{
    classifier: "ssaForm89ecbsv",
    contentType: "application/pdf",
    document: $document,
    subject: { correlationId: "b1" },
    metadata: { SignatureType: "E" }
  }' |
  curl -X PUT "${url}" \
    -H "Authorization: Bearer your_access_token_here" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @-
```

The body it sends, with `document` cut short here (a real one runs to the whole file):

```json
{
  "classifier": "ssaForm89ecbsv",
  "contentType": "application/pdf",
  "document": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI+PgpzdHJlYW0K",
  "subject": {
    "correlationId": "b1"
  },
  "metadata": {
    "SignatureType": "E"
  }
}
```

#### Header Properties

| Property                  | Value                  | Required? |
|---------------------------|------------------------|-----------|
| Authorization             | Bearer *your token*    | true      |
| Content-Type              | application/json       | true      |
| Accept                    | application/json       | false     |
| X-PPS-UserAlias           | *your value*           | false     |
| X-PPS-UserAgent           | *your value*           | false     |
| X-PPS-CorrelationID       | *your value*           | false     |

Send `Content-Type: application/json` on this PUT. In deployed environments a request that arrives without it is refused by edge protection in front of the application, with a `403` carrying an HTML body rather than any response documented here &mdash; and because the service never sees the request, nothing can explain it to you. A local or unprotected deployment may accept the same request, so do not take a working call there as evidence the header is optional.

`Accept` is not enforced &mdash; a request without it is answered normally with JSON &mdash; but send it anyway, so that a future change to content negotiation cannot alter what you receive.

`X-PPS-CorrelationID` is a **support-tracing header and is not the same thing** as the `correlationId` field in a request body. Only the body field is recorded against an order and searched by [Find Workflows](https://docs.pitchpointsolutions.com/api/workflow/list_workflows/); setting the header globally in your HTTP client does not make your orders findable.

See the [Common Headers guide](https://docs.pitchpointsolutions.com/developer_guides/headers/index/) for details on the optional `X-PPS-*` headers above.

A PUT under the same `attachmentId` is safe to repeat, so this call takes no `Idempotency-Key`.

#### Path Parameters

| Property     | Description | Type   |
|--------------|-------------|--------|
| sessionId    | (mandatory) The session to store the document in. | string |
| attachmentId | (mandatory) Your own identifier for the document within this session: 1 to 64 characters from letters, digits, `.`, `_` and `-`. The first PUT under an identifier creates the document; a later PUT under the same identifier replaces it. Use it to [choose documents](https://docs.pitchpointsolutions.com/api/session/start_session_workflow/#choosing-documents) on a workflow start, and to [remove](https://docs.pitchpointsolutions.com/api/session/delete_session_attachment/) one. | string |

Choose identifiers you can recompute, such as `ecbsv-b1` for borrower `b1`'s eCBSV form. A retry after a timeout then lands on the same identifier and leaves one document, not two.

#### Request Data Properties

| Property    | Description | Type   |
|-------------|-------------|--------|
| classifier  | (mandatory) What kind of document this is. One of the values in [Classifiers](https://docs.pitchpointsolutions.com/api/session/put_session_attachment/#classifiers) below. Any other value is a 400. | string |
| contentType | (mandatory) `application/pdf`. The 8821 identity documents also accept `image/jpeg` and `image/png`. It must describe the bytes you send. | string |
| document    | (mandatory) The document, standard base64 ([RFC 4648 section 4](https://www.rfc-editor.org/rfc/rfc4648#section-4)). The URL-safe alphabet is refused. At most 5 MiB once decoded; an image at most 25 megapixels. | string |
| subject     | (optional) Whom the document belongs to: a person, company or employer on the staged loan. Required when the loan holds more than one party it could belong to. A company is matched only when you name it, so always send `subject` for a company's document. See [subject](https://docs.pitchpointsolutions.com/api/session/put_session_attachment/#subject) below. | object |
| metadata    | (optional) What the document itself states, as key/value strings. Only the keys its classifier accepts; see [Classifiers](https://docs.pitchpointsolutions.com/api/session/put_session_attachment/#classifiers). At most 50 keys, and each value a string of at most 1,024 characters; a null value is a 400. | object |

Fields this call doesn't define are ignored.

##### Classifiers

| classifier | Document | Products that take it | Belongs to | `metadata` keys it accepts |
|------------|----------|-----------------------|------------|--------------------------|
| `ssaForm89ecbsv` | Signed SSA-89 for electronic verification | SSAForm89ECBSV | a person | `SignatureType`: `E` (electronic) or `W` (wet ink) |
| `ssaForm89` | Signed SSA-89 | SSAForm89, AutoSSAForm89 | a person | none |
| `irs8821TranscriptAuthorizationConsentCombined` | Signed IRS 8821 consent | IRS8821Transcript | a person, or a company participant | `IRS8821TaxYearsRequested`, `IRS8821FormRequested`, `IRS8821TaxClassificationType` |
| `irs8821TranscriptGovernmentId`, `irs8821TranscriptCurrentPhoto`, `irs8821TranscriptKYCArtifact` | Identity documents carried with an 8821 | IRS8821Transcript | the same party as the consent | none |
| `irs4506t` | Signed IRS 4506-T | IRS4506T, IRS4506TTranscript | a person, or a company participant | `TaxClassificationType`, `FormRequestType`, `irs4506t.request.year.list`, `YearList`, `JointTaxReturnSSN`, `JointTaxReturnPersonName`, `ESIGNIndicator` |
| `mMdv` | Signed M_MDV form | MMdv | a person | none |
| `vvoe`, `voeRework`, `vvoeReconfirm`, `voeFannieMae1005`, `vvoeFreddyMac90`, `voe3rdPartyAuthorization` | The VOE product's own authorization | Vvoe, VoeRework, VvoeReconfirm, VoeFannieMae1005, VvoeFreddieMac90, VOE3rdPartyAuthorization, in the order of the classifiers | a person, and one of their employers | none |

Metadata keys are case-sensitive. A key the classifier doesn't accept is a 400, and so is a value the key doesn't allow.

When a workflow uses the document, its metadata becomes the workflow's preferences of the same keys, unless the workflow start sends its own value for a key. See [Metadata from documents](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/documents/#metadata-from-documents).

##### subject

Name the party one of two ways.

- **By correlation id.** Send the party term's own `correlationId` and nothing else is consulted. This is the reliable way, provided you gave the term its `correlationId` yourself and send the same one every time you stage. One the service generated changes on every stage.
- **By identity.** Send any of the identity fields, as few as you like. Each one you send must match. Names are compared ignoring case and extra spaces, and `ssn` and `ein` by their digits only.

| Property      | Description | Type   |
|---------------|-------------|--------|
| correlationId | (optional) The `correlationId` of the party's term on the staged loan. When sent, it decides alone. | string |
| firstName     | (optional) | string |
| middleName    | (optional) | string |
| lastName      | (optional) | string |
| ssn           | (optional) A person's Social Security number. | string |
| companyName   | (optional) A company participant's name. | string |
| ein           | (optional) A company participant's employer identification number. | string |
| employer      | (optional) For a VOE authorization: which of the person's employers, by the employer term's `correlationId` or its `name`. Required when the person has more than one. | object |

Each field is at most 255 characters, except `ssn` and `ein`, which are at most 64. A longer one is a 400.

**Leave `subject` out and only the loan's borrowers are considered** (and, for a VOE authorization, their employers). A company participant is matched only when you name it, by its `correlationId`, `companyName` or `ein`. So an 8821 or 4506-T sent without a `subject` goes to the borrower, or is refused with `SUBJECT_REQUIRED` when the loan holds several, and never to a company on the loan.

**The document is bound to the identity it matched, not to this snapshot.** The service records the party's names, SSN or EIN, and employer as they stand now. Every later stage records its parties afresh, and the document stays usable for whichever party carries that identity. Restaging with a new address or phone number changes nothing. A restage that changes the identity (a corrected name or SSN, or a loan now staged for someone else) leaves the document in the session but unused; a workflow started for that party answers 409 `ATTACHMENT_REQUIRED` until you attach one for them.

### Responses

**200**

Stored, whether this `attachmentId` is new or replaces a document. The body describes the document, without its bytes. After a replace, workflows started from now on use the new document; a workflow already started with the old one keeps it.

| Property     | Description | Type   |
|--------------|-------------|--------|
| attachmentId | (present) Your identifier for the document. | string |
| classifier   | (present) The classifier you sent. | string |
| contentType  | (present) The content type you sent. | string |
| sizeBytes    | (present) The decoded size of the document, in bytes. | integer |
| subject      | (present) Whom the document is bound to, as recorded from the staged loan. It can carry more than you sent: send a `correlationId` and you get back that party's names. See below. | object |
| updatedAt    | (present) When the document was last stored under this `attachmentId`. | string |
| metadata     | (optional) What the document states. Absent when it states nothing. `JointTaxReturnSSN` shows only its last four digits, as in `*****4321`. | object |

##### subject (response)

| Property     | Description | Type   |
|--------------|-------------|--------|
| firstName    | (optional) | string |
| middleName   | (optional) | string |
| lastName     | (optional) | string |
| ssnLast4     | (optional) The last four digits of the SSN. The full number is never returned. | string |
| companyName  | (optional) | string |
| einLast4     | (optional) The last four digits of the EIN. | string |
| employerName | (optional) The employer a VOE authorization is for. | string |

Each field is omitted rather than null when the party has no value for it.

Example:
```json
{
  "attachmentId": "ecbsv-b1",
  "classifier": "ssaForm89ecbsv",
  "contentType": "application/pdf",
  "sizeBytes": 48213,
  "subject": {
    "firstName": "Jane",
    "lastName": "Sample",
    "ssnLast4": "0001"
  },
  "updatedAt": "2026-08-07T15:04:10Z",
  "metadata": {
    "SignatureType": "E"
  }
}
```

[Read a Session](https://docs.pitchpointsolutions.com/api/session/get_session/) lists every document the session holds in this same shape.

**400**

Nothing was stored. The request can't be used as sent, and the message says what to change: for instance the document isn't base64 or is too large, its bytes aren't the `contentType` you sent, a PDF can't be read, or `metadata` carries a key or value the classifier doesn't accept.

A 400 arrives in **two different body shapes**, decided by how far the request got before it was refused. Branch on the `Content-Type`: `application/json` is the `messages` envelope, and `application/problem+json` is a problem document.

**A value this service evaluated and rejected** carries the `messages` envelope, with `Content-Type: application/json` and the code `VALIDATION_ERROR`.

| Property             | Description                                                                                                  | Type   |
|----------------------|----------------------------------------------------------------------------------------------------------------|--------|
| messages             | (present) Always an array, never null. Carries one message whose `code` is `VALIDATION_ERROR`.                | array  |
| messages[].code      | (present) Always `VALIDATION_ERROR` on this shape.                                                            | string |
| messages[].text      | (present) Human-readable description of what was wrong. Never machine-parsed &mdash; the wording is not contractual. | string |
| messages[].timestamp | (present) RFC 3339 UTC with a trailing `Z`. Fractional seconds appear only when they are not zero, so parse this value rather than slicing it. | string |

Example:
```json
{
  "messages": [
    {
      "code": "VALIDATION_ERROR",
      "text": "metadata value 1 is not a value its key allows",
      "timestamp": "2026-08-07T15:01:42Z"
    }
  ]
}
```

**A request refused before any value was evaluated** carries a problem document instead, with `Content-Type: application/problem+json` and **no `messages` key and no `VALIDATION_ERROR` code**. Its `type` tells you which case it is:

| Cause | `type` |
|-------|--------|
| A body that could not be read as an attachment request at all: malformed JSON, a literal `null` body, a JSON array or bare value where an object was expected, or a field that can't be read as its type | `about:blank` |
| A `Content-Type` header naming a character set this service cannot use. It is refused before the body is read, so it says nothing about what you put in it. | `https://pointservices.com/problems/invalid-request` |

Example:
```json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Malformed JSON",
  "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000"
}
```

> **Warning:** A client that reads `messages[0].code` on every 400 without checking that `messages` exists will throw on the problem-document shape. Branch on the `Content-Type`, or on the presence of `messages`, not on the status.

The session is left exactly as it was. Correct the request and send it again.

**401**

No credential the platform could accept reached the service.

The body is a **JSON problem document**, not the `messages` envelope, and the response carries a `WWW-Authenticate: Bearer realm="Helix"` challenge. Read the machine-readable part from `type`; `title` and `detail` are human copy and are not contractual.

| Property | Description                                                                                          | Type   |
|----------|--------------------------------------------------------------------------------------------------------|--------|
| type     | (present) An absolute URI identifying the problem. `about:blank` when no credential was sent at all.   | string |
| title    | (present) Short human-readable summary.                                                               | string |
| status   | (present) Repeats the HTTP status code.                                                               | number |
| detail   | (present) Human-readable explanation. Never machine-parsed.                                           | string |
| instance | (present) An identifier for this one request. Quote it when contacting support.                       | string |

Examples:
```json
{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required. Present a bearer access token in the Authorization header.",
  "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000"
}

{
  "type": "https://pointservices.com/problems/invalid-token",
  "title": "The access token was not accepted",
  "status": 401,
  "detail": "The access token was rejected.",
  "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000"
}
```

The second form carries `WWW-Authenticate: Bearer realm="Helix", error="invalid_token"`, and is what a token the service will not accept returns.

The `invalid-token` type deliberately does not say why the token was refused: the platform cannot tell an expired token from a revoked, badly signed or malformed one. Treat every `invalid-token` the same way.

> **Warning:** **Refresh your token on a 401, and only on a 401.** An expiring token moves a call from 200 to 401, never to 403. Obtain a fresh access token and retry the request once. If it fails again, stop and surface the error rather than looping &mdash; repeated attempts with a credential the service has already refused will meet the rate throttle described below.

**403**

Your credential was understood but you are not permitted to change this session. Nothing was stored.

A 403 is an **authorization decision**: your identity was established and the answer is still no. It is never a statement about your token, so refreshing the token will not turn it into a 200. A refused request leaves nothing behind, so there is nothing to clean up.

The body is a problem document (`application/problem+json`), not the `messages` envelope, so there is no `code` to branch on. Its `type` is one of two values:

| `type` | Meaning |
|--------|---------|
| `about:blank` | The request was denied before the operation itself ran. |
| `https://pointservices.com/problems/not-authorized` | A policy decision about the specific resource or product you named. |

Example:
```json
{
  "type": "https://pointservices.com/problems/not-authorized",
  "title": "Not authorized",
  "status": 403,
  "detail": "The authenticated identity is not permitted to perform this action.",
  "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000"
}
```

> **Warning:** **A 403 can also come from the edge, before this service is reached,** when a request omits `Content-Type` or carries a value resembling SQL injection or cross-site scripting. That refusal carries an HTML body, not a problem document, and this service never sees it. Check the `Content-Type` of the response before you parse it. A value that legitimately contains such text should be encoded &mdash; Base64, for instance &mdash; rather than sent raw.

**404**

No session exists with this identifier, or the path you called is not served.

When this API answers, the body is a problem document (`application/problem+json`) in both cases, and its `type` tells them apart.

**`https://pointservices.com/problems/not-found`** means the identifier you sent did not resolve.

| Property | Description                                                                              | Type   |
|----------|--------------------------------------------------------------------------------------------|--------|
| type     | (present) `https://pointservices.com/problems/not-found` here. Compare it as the whole URI. | string |
| title    | (present) Short human-readable summary.                                                   | string |
| status   | (present) Repeats the HTTP status code.                                                   | number |
| detail   | (present) Human-readable explanation naming what was not found. Never machine-parsed.     | string |
| instance | (present) An identifier for this one request. Quote it when contacting support.           | string |

Example:
```json
{
  "type": "https://pointservices.com/problems/not-found",
  "title": "No such resource",
  "status": 404,
  "detail": "Session[0000000000013500001] not found",
  "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000"
}
```

Treat this as a single outcome: nothing in the body narrows down why the identifier did not resolve. Check the identifier you sent, and the tenancy of the credential you sent it with. An identifier this API has already issued to you is readable the moment you receive it, so a 404 on one is final rather than a race. Retrying will not make it appear.

**`about:blank`** means the path itself is not served here, so the request never reached this operation: a wrong host, or an environment where this API is not deployed.

A URL missing the `/riskinsight-services-ws/resources/v1` path prefix does not reach this API at all. The 404 then comes from infrastructure in front of it, and carries no body this API defines, so don't try to parse it. If a 404 has no problem document, check the path prefix before anything else.

**409**

The request is well formed but doesn't fit the loan the session holds now. Nothing was stored, and the code names the fix.

`SESSION_EMPTY` &mdash; nothing has been staged, so there is nobody to attach a document to. [Stage the loan](https://docs.pitchpointsolutions.com/api/session/stage_session_sami/) first.

`SUBJECT_REQUIRED` &mdash; you sent no `subject`, and the loan holds more than one party the document could belong to. Name one.

`SUBJECT_UNKNOWN` &mdash; the `subject` matches nobody on the staged loan. Check it against what you staged, or stage the party first.

`SUBJECT_AMBIGUOUS` &mdash; the `subject` matches more than one party. Add a field, or send the party's `correlationId`.

**Branch on the `Content-Type` first, and only then on `messages[].code`.** A 409 here arrives in two body shapes, and the corrective action differs by cause. Never branch on the status alone, and never read `messages[0].code` without checking that `messages` is present.

**`application/json`** carries the `messages` envelope:

| Property             | Description                                                                                             | Type   |
|----------------------|-----------------------------------------------------------------------------------------------------------|--------|
| messages             | (present) Always an array, never null.                                                                   | array  |
| messages[].code      | (present) One of the codes described above for this status.                                              | string |
| messages[].text      | (present) Human copy. Never machine-parsed.                                                              | string |
| messages[].timestamp | (present) RFC 3339 UTC with a trailing `Z`, fractional seconds only when they are not zero.              | string |

**`application/problem+json`** carries a problem document with `type` `https://pointservices.com/problems/concurrent-modification` and no `messages` key. Another request changed the same resource while yours was in flight, and **nothing from yours was applied**. It carries no `Retry-After`, deliberately: read the resource again, decide whether your change still applies to what you now see, and resubmit only if it does. Don't resend the same request on a timer.

Example:
```json
{
  "type": "https://pointservices.com/problems/concurrent-modification",
  "title": "Concurrent modification",
  "status": 409,
  "detail": "The resource was modified by another request while this one was being processed. This request was not applied; re-read the resource before resubmitting.",
  "instance": "urn:pps:request:0000000000000000000000000000000000000000000000000000"
}
```

In either shape the conflict is final for that attempt: the service does not retry it for you.

**429**

Refused by a rate throttle at the edge, before this service is reached. The throttle counts requests per source address across every endpoint on both the session and workflow surfaces. Because the edge sends this response before the request reaches the service, it is not described in the OpenAPI specifications or the API Explorer.

The refusal carries no body, no `messages` array and no `Retry-After` header, and this service never sees it, so it will not appear in any support trace.

Back off and resume. When following a workflow to completion, an interval that stays clear of the throttle is two seconds for the first two checks, then five, then ten seconds thereafter, with an overall deadline after which you stop and investigate.

**500**

An unhandled failure inside the service. The body is a problem document (`application/problem+json`) with `type` `about:blank`, not the `messages` envelope, so branch on the status alone. When you report the error to PPS, quote the document's `instance`: it carries the same id as the `x-pps-request-id` response header, and it is what lets PPS find this exact request.

**Retrying this call is safe.** Send the same PUT again, under the same `attachmentId`. It leaves one document under that identifier whether or not the first attempt stored it.
