Beta
Documents and Subjects
Some products run for one person on the loan rather than for the whole loan, and some need a signed form before they can run. This page shows how to say whom a workflow is for, how to attach the forms it needs, and how the two fit together. It ends with a complete run of eCBSV, SSA’s electronic Consent Based SSN Verification, for two borrowers.
Read Getting Started first. This page uses the session route it describes: start a session, stage, then start workflows against it.
- The idea in brief
- Who a workflow is for
- Attaching documents
- Which documents a workflow uses
- Metadata from documents
- Replacing and removing documents
- Limits
- End to end: eCBSV for two borrowers
- Errors you will meet
The idea in brief
sequenceDiagram
autonumber
participant You
participant PPS
You->>PPS: POST /v1/sessions/{id}/sami (two borrowers, b1 and b2)
You->>PPS: PUT /v1/sessions/{id}/attachments/ecbsv-b1 (subject b1)
You->>PPS: PUT /v1/sessions/{id}/attachments/ecbsv-b2 (subject b2)
You->>PPS: POST /v1/sessions/{id}/workflows (subject b1)
PPS-->>You: 202, uses ecbsv-b1
You->>PPS: POST /v1/sessions/{id}/workflows (subject b2)
PPS-->>You: 202, uses ecbsv-b2
- A document belongs to the session, and to one person, company or employer on the loan it holds. You attach it once and every later workflow for that party can use it.
- A workflow names whom it is for in
subject. With one borrower on the loan you can leave it out. - The workflow finds its own documents: the subject’s newest document of each kind the product takes. You name documents only to choose different ones.
Who a workflow is for
Products such as eCBSV and the SSA-89 run for one person, and the IRS 8821 and 4506-T for one person or company. Name that party in the workflow start’s subject:
{
"product": { "service": "SSAForm89ECBSV", "model": "PDF-001" },
"subject": { "correlationId": "b1" }
}
Name the party one of two ways:
- By the
correlationIdon their term. This is the reliable way. Give everyperson,participantand employer term acorrelationIdof your own, and send the same one every time you stage. AcorrelationIdthe service generates for you changes on every stage, so it can’t name anyone. - By identity: any of
firstName,middleName,lastName,ssn,companyNameandein, as few as you like. Each field you send must match. Names are compared ignoring case and extra spaces, and SSNs and EINs by their digits.
What happens when the subject doesn’t pick out exactly one party:
| You send | The loan holds | Answer |
|---|---|---|
no subject | one party the product could be for | The workflow runs for that party. |
no subject | several | 409 SUBJECT_REQUIRED. Name one. |
a subject | nobody it matches | 409 SUBJECT_UNKNOWN. |
a subject | several it matches | 409 SUBJECT_AMBIGUOUS. Add a field, or send the correlationId. |
a subject, for ADV or another product run for the loan or a property | anything | 400. These products take no subject. |
A company is matched only when you name it. With no subject, only the loan’s borrowers count as “the party the product could be for”, so an 8821 or 4506-T workflow or document with no subject is for the borrower, never for a company participant on the loan. To order or attach for a company, name it in subject by its correlationId, companyName or ein.
A verification of employment also names one of the person’s employers, in subject.employer, by the employer term’s correlationId or its name.
Attaching documents
Attach a Document stores one document under an identifier you choose:
PUT /v1/sessions/{sessionId}/attachments/{attachmentId}
The body carries the document’s kind (classifier), its contentType, the document itself in base64, the subject it belongs to, and optionally what it states (metadata). A PUT answers 200, and a later PUT under the same attachmentId replaces the document. That makes a PUT safe to retry: pick identifiers you can recompute, such as ecbsv-b1, and a retry after a timeout lands on the same document.
Stage before you attach. The document is matched to a party on the loan the session holds now, and a session with nothing staged answers 409 SESSION_EMPTY.
A document is bound to an identity, not to a snapshot. The service records the party’s names, SSN or EIN, and employer when you attach the document. Each later stage records its parties afresh, and the document stays usable for whichever party still carries that identity:
- Restaging with the same people and a new address, phone or income changes nothing. The documents still belong to them.
- Restaging with a corrected name or SSN, or for different people, leaves the document in the session but unused. A workflow for that party answers 409
ATTACHMENT_REQUIRED, naming whom the document is missing for. Attach one for them.
Two people the identity can’t tell apart, such as a Jr and Sr staged without SSNs, can’t use each other’s documents, or their own. Stage their SSNs.
Read a Session lists the documents the session holds in session.attachments, oldest first. A listed document shows only the last four digits of its subject’s SSN or EIN, and no call returns a document’s bytes.
Which documents a workflow uses
Of each kind the product takes, a workflow uses the subject’s newest document: the one whose latest PUT came last. It carries at most one of each kind.
So you rarely name documents. When a borrower re-signs a form, attach the new one, under the same attachmentId or a new one, and the next workflow uses it.
Send attachmentIds to choose differently, for instance to use an older form:
{
"product": { "service": "SSAForm89ECBSV", "model": "PDF-001" },
"subject": { "correlationId": "b2" },
"attachmentIds": ["ecbsv-b2"]
}
The list replaces the automatic choice entirely, so list every document the workflow should use. Each one must belong to the subject. A list that names two of one kind, or leaves out a kind the product requires, is a 400.
A workflow already started keeps the documents it started with. Replacing or removing a document later doesn’t change it.
Metadata from documents
Some forms state settings the product needs. An SSA-89 for eCBSV states how it was signed; an IRS 8821 consent states which tax years and forms it authorizes. Send those as the document’s metadata when you attach it, and every workflow that uses the document takes them as its preferences of the same keys. You don’t repeat them on each start.
| classifier | Keys it accepts |
|---|---|
ssaForm89ecbsv | SignatureType |
irs8821TranscriptAuthorizationConsentCombined | IRS8821TaxYearsRequested, IRS8821FormRequested, IRS8821TaxClassificationType |
irs4506t | TaxClassificationType, FormRequestType, irs4506t.request.year.list, YearList, JointTaxReturnSSN, JointTaxReturnPersonName, ESIGNIndicator |
| any other | none |
The rules when a workflow uses a document:
- The workflow start wins. A value in the start’s own
preferencesbeats the document’s metadata for the same key, so a workflow can ask for less than a form covers, such as two of the four tax years a consent authorizes. - On a new start, only the documents the workflow uses count. A replaced or removed document’s metadata never reaches it, and a replacement that states nothing passes nothing on, even if the document it replaced did.
- A reconfirm is different. It inherits the newest run’s preferences, including those a document supplied, and those beat what a replacement document states. Send the key in the reconfirm body to change it.
- A key the product doesn’t use is left out, without an error.
- The values are checked when you attach, so a wrong value is a 400 on the PUT. A value can still go stale before a workflow uses it, such as a tax year that has aged out, and that workflow then fails with the reason in its messages.
JointTaxReturnSSN comes back masked on every read, as *****4321.
Replacing and removing documents
A replacing PUT and a DELETE both take the old document out of the session: it stops being listed and no later workflow can use it.
- A document no workflow has used is deleted.
- A document a workflow has used is kept for that workflow, which goes on as it started. The session no longer lists it.
A reconfirm without terms, of a workflow started in a session, runs for the same party and uses the session’s current documents for them, as a new start would. If the session no longer holds a document the product requires for that party, the reconfirm answers 409 ATTACHMENT_REQUIRED. A reconfirm that carries terms chooses no documents, so stage first and reconfirm without terms. See Documents on a reconfirm.
Limits
- Each document is at most 5 MiB once decoded, and an image at most 25 megapixels.
- A session holds as many documents as you attach, and a workflow carries every document its product takes, whatever their total size.
- PDFs are checked for readability when you attach them. An unreadable PDF is a 400 and is never stored.
End to end: eCBSV for two borrowers
eCBSV verifies a person’s name, SSN and date of birth with SSA, on the authority of an SSA-89 the person signed. It runs for one person, so a loan with two borrowers takes two workflows, each with its own signed form.
Ask your PPS account manager for three things before you start: eCBSV enabled for your account, with the service and model to send (this page uses SSAForm89ECBSV and PDF-001); your company’s EIN configured on the product, because this API doesn’t accept an EIN preference; and the webhook endpoint from Getting Started, registered for SSAForm89ECBSV.
Each borrower needs a first name, last name, SSN and date of birth on the staged loan, and a signed SSA-89 as a PDF.
Step 1: Start a session
curl -X POST https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c0a52-3b7e-4c1d-9a8e-2f4b6d0c9e17" \
-d '{
"correlationId": "my-loan-0002"
}'
Keep session.sessionId; every call below uses it. This page uses 0000000000013500001.
Step 2: Stage both borrowers
Give each person term a correlationId of your own. Those two values, b1 and b2, are how you name the borrowers from here on.
curl -X POST https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001/sami \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-d '{
"terms": [
{
"person": {
"correlationId": "b1",
"firstName": "Jane",
"lastName": "Sample",
"ssn": "000-00-0001",
"dob": "01/31/1980"
}
},
{
"person": {
"correlationId": "b2",
"firstName": "John",
"lastName": "Sample",
"ssn": "000-00-0002",
"dob": "07/04/1978"
}
}
]
}'
The answer is 200 with dataStaged: true. Stage the whole loan your other products need; this example carries only what eCBSV reads.
Step 3: Attach each borrower’s signed SSA-89
One PUT per borrower, each naming its borrower in subject. The form states how it was signed in SignatureType: E for electronic, W for wet ink. Jane signed electronically and John on paper.
url="https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001/attachments"
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}/ecbsv-b1" \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-d @-
base64 < ssa89-john.pdf | tr -d '\n' > ssa89-john.b64
jq -n --rawfile document ssa89-john.b64 '{
classifier: "ssaForm89ecbsv",
contentType: "application/pdf",
document: $document,
subject: { correlationId: "b2" },
metadata: { SignatureType: "W" }
}' |
curl -X PUT "${url}/ecbsv-b2" \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-d @-
Each answers 200 with the document it stored. The subject comes back as the service recorded it from the loan, so you can check the form landed on the right person:
{
"attachmentId": "ecbsv-b2",
"classifier": "ssaForm89ecbsv",
"contentType": "application/pdf",
"sizeBytes": 51874,
"subject": {
"firstName": "John",
"lastName": "Sample",
"ssnLast4": "0002"
},
"updatedAt": "2026-08-07T15:04:12Z",
"metadata": {
"SignatureType": "W"
}
}
Step 4: Check what the session holds
curl -X GET https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001 \
-H "Authorization: Bearer your_access_token_here" \
-H "Accept: application/json"
{
"session": {
"sessionId": "0000000000013500001",
"dataStaged": true,
"correlationId": "my-loan-0002",
"attachments": [
{
"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" }
},
{
"attachmentId": "ecbsv-b2",
"classifier": "ssaForm89ecbsv",
"contentType": "application/pdf",
"sizeBytes": 51874,
"subject": { "firstName": "John", "lastName": "Sample", "ssnLast4": "0002" },
"updatedAt": "2026-08-07T15:04:12Z",
"metadata": { "SignatureType": "W" }
}
]
},
"messages": []
}
Step 5: Start one workflow per borrower
Each start names its borrower. Neither names a document or a SignatureType: each workflow finds its borrower’s form and takes the signature type the form states.
url="https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001/workflows"
curl -X POST "${url}" \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b9d4f3e-8a21-4c6b-b7d5-1e3f9a2c6d48" \
-d '{
"product": { "service": "SSAForm89ECBSV", "model": "PDF-001" },
"subject": { "correlationId": "b1" },
"correlationId": "my-loan-0002-ecbsv-b1"
}'
curl -X POST "${url}" \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5c2e7a19-d034-4f8b-9e61-7a4b2d8c0f53" \
-d '{
"product": { "service": "SSAForm89ECBSV", "model": "PDF-001" },
"subject": { "correlationId": "b2" },
"correlationId": "my-loan-0002-ecbsv-b2"
}'
Each answers 202 with its own workflowId:
{
"workflow": {
"workflowId": "wfpop_0000000000002080001",
"runId": "wfrunpop_0000000000002080001",
"sessionId": "0000000000013500001",
"correlationId": "my-loan-0002-ecbsv-b1",
"product": {
"service": "SSAForm89ECBSV",
"model": "PDF-001"
},
"productType": "SSAForm89ECBSV",
"productName": "PDF-001",
"status": "processing",
"reconfirmAvailable": false
},
"messages": [
{
"code": "ACCEPTED",
"text": "workflow accepted for processing",
"timestamp": "2026-08-07T15:05:01Z"
}
]
}
Give each workflow its own correlationId, as here, so you can find either one again with Find Workflows.
Leave out subject and the start is refused, because the loan holds two borrowers eCBSV could be for. Nothing is started or billed:
{
"messages": [
{
"code": "SUBJECT_REQUIRED",
"text": "the session's loan holds more than one party this could be for; name the subject",
"timestamp": "2026-08-07T15:05:01Z"
}
]
}
Step 6: Wait for the result
An eCBSV workflow doesn’t finish in seconds. A person at PPS reviews each signed form before the request goes to SSA, so expect it to take a while. The workflow reads processing until that review and SSA’s answer are both done.
Wait for the workflow.updated or workflow.failed delivery for each workflowId, as in Getting Started. If you poll Read a Workflow instead, poll each workflow every few minutes rather than every few seconds.
status | What it means for eCBSV |
|---|---|
processing | Waiting for the form’s review, or for SSA. |
complete | The report is ready. A form the review turned down also ends complete, without a request to SSA; its report says so. |
failed | The request to SSA failed, or the workflow couldn’t run. There is no report, and the messages say why. A missing SignatureType fails here, for instance. |
complete doesn’t mean verified. Read the report to find out what SSA said.
Step 7: Download each report
The result is a PDF report: whether SSA matched the name, SSN and date of birth, and whether it reported a death indicator, or why the form was turned down. The Findings API serves it. First read the workflow’s summary, which lists the report without side effects:
curl -X GET "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002080001" \
-H "Authorization: Bearer your_access_token_here"
{
"workflowId": "wfpop_0000000000002080001",
"severityCounts": [],
"reports": [
{
"name": "SSAForm89ECBSV.pdf",
"contentType": "application/pdf",
"links": {
"download": {
"src": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002080001/reports/_latestpdf/content"
}
}
}
]
}
Then fetch links.download.src once, when you want the document:
curl -X GET "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002080001/reports/_latestpdf/content" \
-H "Authorization: Bearer your_access_token_here" \
-o ecbsv-b1.pdf
Fetching the download has side effects. It records that the report was read. Don’t poll it to see whether a report exists: reports is [] until there is one. See Get a Workflow’s Findings Summary.
Do the same with John’s workflowId.
Step 8: A borrower re-signs
Say John’s form has to be signed again. Attach the new one under the same attachmentId:
base64 < ssa89-john-resigned.pdf | tr -d '\n' > ssa89-john-resigned.b64
jq -n --rawfile document ssa89-john-resigned.b64 '{
classifier: "ssaForm89ecbsv",
contentType: "application/pdf",
document: $document,
subject: { correlationId: "b2" },
metadata: { SignatureType: "E" }
}' |
curl -X PUT "https://api.pointservices.com/riskinsight-services-ws/resources/v1/sessions/0000000000013500001/attachments/ecbsv-b2" \
-H "Authorization: Bearer your_access_token_here" \
-H "Content-Type: application/json" \
-d @-
It answers 200 and replaces the form. The workflow already started for John keeps the form it started with. A new workflow for b2 uses the re-signed form and its SignatureType of E, with no change to the start body from Step 5.
Had you attached the new form under a new identifier, say ecbsv-b2-v2, the session would hold both, and a new workflow for b2 would still use the re-signed one, because it was stored last. To use the older one, send "attachmentIds": ["ecbsv-b2"].
A complete run
host="https://api.pointservices.com/riskinsight-services-ws/resources/v1"
tok="your_access_token_here"
sid="0000000000013500001" # from step 1
# 1. start a session -> returns sessionId
curl -s -X POST "${host}/sessions" \
-H "Authorization: Bearer ${tok}" \
-H "Content-Type: application/json" \
-d '{"correlationId":"my-loan-0002"}'
# 2. stage both borrowers, each with your own correlationId
curl -s -X POST "${host}/sessions/${sid}/sami" \
-H "Authorization: Bearer ${tok}" \
-H "Content-Type: application/json" \
-d '{"terms":[{"person":{"correlationId":"b1","firstName":"Jane","lastName":"Sample","ssn":"000-00-0001","dob":"01/31/1980"}},{"person":{"correlationId":"b2","firstName":"John","lastName":"Sample","ssn":"000-00-0002","dob":"07/04/1978"}}]}'
# 3. attach each borrower's signed SSA-89 -> 200 each
for who in b1:jane:E b2:john:W; do
IFS=: read -r cid name sig <<< "${who}"
base64 < "ssa89-${name}.pdf" | tr -d '\n' > "ssa89-${name}.b64"
jq -n --rawfile document "ssa89-${name}.b64" --arg cid "${cid}" --arg sig "${sig}" \
'{classifier:"ssaForm89ecbsv",contentType:"application/pdf",document:$document,subject:{correlationId:$cid},metadata:{SignatureType:$sig}}' |
curl -s -X PUT "${host}/sessions/${sid}/attachments/ecbsv-${cid}" \
-H "Authorization: Bearer ${tok}" \
-H "Content-Type: application/json" \
-d @-
done
# 4. check the session holds both forms
curl -s -X GET "${host}/sessions/${sid}" \
-H "Authorization: Bearer ${tok}"
# 5. one workflow per borrower -> 202 each, with its own wfpop_ workflowId. Each is billed.
for cid in b1 b2; do
curl -s -X POST "${host}/sessions/${sid}/workflows" \
-H "Authorization: Bearer ${tok}" \
-H "Content-Type: application/json" \
-d "{\"product\":{\"service\":\"SSAForm89ECBSV\",\"model\":\"PDF-001\"},\"subject\":{\"correlationId\":\"${cid}\"},\"correlationId\":\"my-loan-0002-ecbsv-${cid}\"}"
done
# 6. a delivery arrives for each workflowId, or read one
curl -s -X GET "${host}/workflows/wfpop_0000000000002080001" \
-H "Authorization: Bearer ${tok}"
# 7. once complete, list the report, then download it once from its links.download.src
curl -s -X GET "${host}/findings/workflows/wfpop_0000000000002080001" \
-H "Authorization: Bearer ${tok}"
curl -s -X GET "${host}/findings/workflows/wfpop_0000000000002080001/reports/_latestpdf/content" \
-H "Authorization: Bearer ${tok}" \
-o ecbsv-b1.pdf
Errors you will meet
| Status and code | Call | Fix |
|---|---|---|
409 SESSION_EMPTY | attach, start | Stage the loan first. |
409 SUBJECT_REQUIRED | attach, start | Name the party in subject. |
409 SUBJECT_UNKNOWN | attach, start | The subject matches nobody on the loan. Check it against what you staged. |
409 SUBJECT_AMBIGUOUS | attach, start | Add a field, or send the party’s correlationId. |
409 ATTACHMENT_REQUIRED | start, reconfirm | Attach the document the text names for that party, then send again. |
400 VALIDATION_ERROR | attach | The document, its content type, its classifier or its metadata is wrong; the text says which. |
400 VALIDATION_ERROR | start | A subject the product doesn’t take, an attachmentIds problem, or a preferences key the product doesn’t publish. |
None of these starts or bills anything. Error Handling covers the two error shapes and how to branch on them.