Questionnaire: documents and the bank · Social Matter Payments API

POST /v1/applications/current/documents

Upload a document, sealed byte for byte before storage (10 MB). ID photos and selfies are photos only, never a PDF.

Applicant session

Host https://onboard.socialmatterspay.com

An owner’s own link may upload only that owner’s photos. A selfie is the person’s own: it is taken in that person’s own session (the applicant for the owner marked “This is me”, everyone else on their own emailed link), only after they agreed to the face match; otherwise 403 selfie_is_personal or 409 consent_needed. The applicant may add another owner’s ID front and back, which a person at SMP reviews without a face match.

Request body (multipart/form-data)

Field	Notes
`file` requiredstring (binary)	—
`doc_type` requiredenum	one of `id_front`, `id_back`, `selfie`, `ein_letter`, `articles`, `dba_certificate`, `terms_page`, `bank_statement`, `voided_check`, `bank_letter`, `account_document`, `other`
`owner_id`string	For id_front, id_back and selfie
`statement_month`string	YYYY-MM, for bank_statement: the current month or the four before it
`source`enum	one of `upload`, `camera`

Responses

Status	Meaning
`201`	The document and the application
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`413`	Error — error shape and codes
`415`	Error — error shape and codes

Fields of `data` (201)

Field Notes

documentobject

7 child fields

`id`string	—
`doc_type`string	A key from config.document_types.
`owner_id`string \| null	The person an ID photo or selfie belongs to. Null for the business's documents.
`filename`string	The name as stored: control characters and slashes replaced, at most 120 characters.
`size_bytes`integer	—
`sha256`string	SHA-256 of the file as uploaded.
`statement_month`string \| null	YYYY-MM, for a bank statement. Null for other documents.

applicationobject

The application as its applicant sees it. An owner who opened their own emailed link gets a limited view, with only owner_scope, legal_name, that owner and the config; the other fields are for the applicant.

26 child fields

objectstring = "application" —

idstring —

referencestring The application's reference.

statusenum one of draft, submitted, info_requested, approved, declined

owner_scopeboolean = true Present and true only in the limited view an owner gets on their own link.

legal_namestring | null Present only in the limited owner view.

started_byenum Who started the application. one of applicant, partner, agent

info_request_messagestring | null What SMP asked for, while status is info_requested. Null otherwise.

contactobject

4 child fields

`name`string \| null	—
`email`string	—
`phone`string \| null	—
`email_verified`boolean	—

businessobject

12 child fields

legal_namestring | null —

dba_namestring | null —

entity_typeenum one of llc, c_corporation, s_corporation, partnership, nonprofit,

formation_statestring | null Two-letter state code.

formation_datestring | null (date) —

ein_last4string | null The last four digits of the EIN. The full number is never returned.

addressobject

5 child fields

`line1`string \| null	—
`line2`string \| null	—
`city`string \| null	—
`state`string \| null	—
`postal_code`string \| null	—

business_phonestring | null —

website_urlstring | null —

name_differsboolean | null Whether the legal name differs from the name on the website. Null until answered.

terms_page_urlstring | null —

name_link_proofenum The proof that links the legal name to the website name, as worked out from the answers and documents so far. one of not_needed, dba_certificate, terms_page, domain_email_ein_letter,

salesobject

10 child fields

`products_description`string \| null	—
`category`string \| null	A key from config.categories.
`monthly_volume_cents`integer \| null	—
`avg_ticket_cents`integer \| null	—
`max_ticket_cents`integer \| null	—
`refund_policy`string \| null	—
`current_processors`array of string	The processors the business uses today.
`integration_types`array of string	Keys from config.integration_types.
`is_startup`boolean \| null	True when the business has no three months of bank statements yet.
`statement_descriptor`string \| null	—

ownersarray of object

17 child fields

idstring —

full_namestring —

titlestring | null —

ownership_pctnumber Percent owned, 0 to 100, to two decimals.

is_control_personboolean —

is_applicantboolean True for the person marked "This is me".

dobstring (date) —

emailstring | null —

phonestring | null —

addressobject

5 child fields

`line1`string \| null	—
`line2`string \| null	—
`city`string \| null	—
`state`string \| null	—
`postal_code`string \| null	—

ssn_last4string —

id_statusenum one of not_started, pending, verified, failed, manual_review

biometric_consentboolean | null True when the person agreed to the face match, false when they declined, null when unanswered.

consentobject

The release for the face match as it stands.

7 child fields

`can_answer`boolean	Whether this session may answer for the person: the applicant for the owner marked "This is me", or an owner on their own link.
`by`enum	Who gave the answer. one of `applicant`, `owner`,
`at`string \| null (date-time)	—
`version`string \| null	The version of the notice agreed to or declined.
`sentence`string \| null	The release sentence with the person's name, when they agreed.
`sentence_sha256`string \| null	—
`locked`boolean	True once an ID check has run: the answer can no longer be changed here.

invite_sent_atstring | null (date-time) When the person was last emailed their own link.

documentsobject

3 child fields

`id_front`object \| null	The person's current photo of this kind. Null when none has been added.
`id_back`object \| null	The person's current photo of this kind. Null when none has been added.
`selfie`object \| null	The person's current photo of this kind. Null when none has been added.

verificationobject | null

The latest ID check of the person. Null when none has run.

12 child fields

`provider`enum	one of `plaid`, `sandbox`, `manual`
`status`enum	one of `pending`, `verified`, `failed`, `manual_review`
`provider_status`string \| null	Plaid's own status for the session, such as active or success. Null for sandbox and manual checks.
`sandbox`boolean	True when the built-in test provider ran the check.
`checks`object	What was checked and how it came out. No personal data.
`created_at`string (date-time)	—
`completed_at`string \| null (date-time)	—
`attempt`integer	Which Plaid attempt this is, from 1.
`retry_available`boolean	Plaid only: another try is allowed because the last attempt ended without a pass and fewer than the allowed attempts were made.
`attempts_left`integer \| null	Plaid only: attempts remaining. Null for other providers.
`reason`string \| null	Plaid only: why a failed attempt did not pass, in plain words. Null otherwise.
`fell_back`enum	When Plaid could not finish the job and a person at SMP has it, tries (the attempts were used up) or unreachable (the vendor or its setup failed). false otherwise. one of `tries`, `unreachable`, `false`

ownership_attestedboolean Whether the applicant confirmed the list of owners is complete.

documentsarray of object

The business's documents (those that belong to no person).

7 child fields

`id`string	—
`doc_type`string	A key from config.document_types.
`statement_month`string \| null	YYYY-MM, for a bank statement.
`filename`string	—
`content_type`string	—
`size_bytes`integer	—
`uploaded_at`string (date-time)	—

statement_monthsarray of string The months in the accepted window that the bank statements added so far cover, oldest first.

bankobject | null

The payout account. Null until one is connected.

9 child fields

`method`enum	one of `plaid`, `plaid_sandbox`, `manual`
`status`enum	one of `verified`, `name_mismatch`, `manual_review`, `rejected`
`institution_name`string \| null	—
`account_type`enum	one of `checking`, `savings`
`account_last4`string	—
`routing_number`string	The 9-digit routing number of the account.
`holder_name`string	—
`name_match`enum	How the names on the account compared with the business and its owners. one of `match`, `partial`, `mismatch`, `unavailable`
`sandbox`boolean	True when the account is Plaid's test account.

referralobject

5 child fields

`status`enum	one of `none`, `attributed`, `pending_review`, `invalid`, `withheld`, `rejected`
`source`enum	one of `link`, `code`, `partner_portal`, `claim`, `admin`,
`partner_name`string \| null	—
`agent_name`string \| null	—
`claim`string \| null	Who the applicant said referred them, as typed.

integrationobject | null

The one website or app the account will use the API on, its sandbox account and its review. Null until the first page names it.

18 child fields

kindenum one of website, app

domainstring The website's domain, or the domain an app's server uses.

app_namestring | null —

app_platformenum one of ios, android, web, desktop,

app_store_urlstring | null —

app_bundle_idstring | null —

methodenum How the business connects: the API, the WooCommerce plugin, or the hosted checkout and invoices. Only api runs the certification cases. one of api, plugin, hosted

labelstring Where the account is used, such as example.com or "Acme (iOS app) · api.example.com".

sandboxobject | null

The sandbox account. Never carries its key. Null until it is made.

3 child fields

`account_id`string	—
`key_prefix`string \| null	—
`issued_at`string \| null (date-time)	—

statusenum one of building, submitted, changes_requested, approved, switched_off

page_urlstring | null The page submitted for review.

applicant_notesstring | null —

submitted_atstring | null (date-time) —

due_atstring | null (date-time) When the review is answered by: 2 business days after submitting.

placeinteger | null Place in the review line while status is submitted, oldest first. Null otherwise.

decisionobject | null

The review's decision, once there is one (changes requested, approved or switched off).

3 child fields

`status`enum	one of `changes_requested`, `approved`, `switched_off`
`at`string \| null (date-time)	—
`reason`string \| null	—

casesarray of object

The certification cases the method runs. Empty unless method is api.

3 child fields

`id`string	—
`title`string	—
`how`string	How to make the case happen in the sandbox.

page_checksarray of object

What a person looks at on the submitted page.

3 child fields

`id`string	—
`title`string	—
`looks_at`string	—

pricingobject | null

The price a partner proposed. Null when no partner proposed one.

3 child fields

proposedobject

3 child fields

`bps`integer	—
`fixed_cents`integer	—
`cap_cents`integer \| null	—

proposed_textstring —

notestring —

agreementsarray of object

The documents to sign. Empty until a payout bank account is connected.

5 child fields

`key`string	—
`title`string	—
`box`enum	one of `agreements`, `consents`
`version`string	—
`draft`boolean	—

signaturesarray of object

One record per box signed.

4 child fields

idstring —

boxenum one of agreements, consents

submitted_atstring (date-time) —

documentsarray of object

3 child fields

`key`string	—
`title`string	—
`signed_sha256`string	SHA-256 of the signed PDF as stored.

signed_documentsarray of object

5 child fields

`key`string	—
`title`string	—
`box`enum	one of `agreements`, `consents`
`signed_at`string (date-time)	—
`signed_sha256`string	—

submitted_atstring | null (date-time) —

reviewobject | null

The business check while it waits. Null otherwise.

2 child fields

`due_at`string (date-time)	When the check is answered by: 2 business days after submitting.
`place`integer \| null	Place in the review line, oldest first.

problemsarray of object

What still stops the application from being submitted. Empty once it is submitted.

4 child fields

`step`enum	one of `contact`, `business`, `sales`, `owners`, `identity`, `bank`, `documents`, `sign`
`item`integer \| null	1 to 14 for an item of the merchant submission list; null for the rest of the business check.
`field`string	—
`message`string	—

configobject

The lists and rules the questionnaire draws its choices from, so the browser hard-codes none of them.

13 child fields

entity_typesobject

Business types, each key mapped to the label shown for it.

5 child fields

`llc`string	—
`c_corporation`string	—
`s_corporation`string	—
`partnership`string	—
`nonprofit`string	—

categoriesarray of object

4 child fields

`key`string	The value to send as the category.
`label`string	—
`group`enum	one of `Business to business`, `Consumer`, `Only with a bank’s written approval`
`bank_approval_required`boolean	True when no merchant in the category goes live until a bank has approved the category in writing.

prohibitedarray of string Kinds of business that are never accepted. Shown on the questionnaire, not selectable.

integration_typesobject

The ways to connect, each key mapped to its label and a note.

6 child fields

`woocommerce`object	—
`api`object	—
`shopify`object	—
`checkout`object	—
`invoices`object	—
`not_sure`object	—

document_typesobject

The document types an upload can carry, each key mapped to the label shown for it.

12 child fields

`id_front`string	—
`id_back`string	—
`selfie`string	—
`ein_letter`string	—
`articles`string	—
`dba_certificate`string	—
`terms_page`string	—
`bank_statement`string	—
`voided_check`string	—
`bank_letter`string	—
`account_document`string	—
`other`string	—

name_link_proofsobject

The proofs that link the legal name to a different name on the website, each key mapped to its label.

4 child fields

`not_needed`string	—
`dba_certificate`string	—
`terms_page`string	—
`domain_email_ein_letter`string	—

statesarray of string Two-letter codes of the US states and territories the questionnaire accepts.

statement_windowarray of string The five months (YYYY-MM, this month first) a bank statement may cover.

biometric_consentobject

The biometric notice and the release for the face match, word for word. The person's name goes in the blank of the release.

6 child fields

`version`string	Send this as version when agreeing; a changed notice is refused.
`draft_stamp`string	The draft notice stamped on the document while counsel has not approved it.
`sections`array of object	—
`text`string	The release sentence, with name_blank where the person's full legal name goes.
`name_blank`string	The placeholder in text that the person's name replaces.
`notice_sha256`string	SHA-256 of the notice as it stands, stored with every answer.

id_attemptsinteger How many automatic ID check attempts a person gets before a person at SMP takes over.

bank_modeenum How the payout account is proved here. plaid with Plaid keys, sandbox with Plaid's test account outside production, document_only with a voided check, bank letter or bank document. one of plaid, sandbox, document_only

idv_modeenum Who checks the owners' IDs. plaid is Plaid Identity Verification, sandbox is the built-in test provider, manual is a person at SMP. one of plaid, sandbox, manual

sandboxboolean True outside production.

Example

Add a document (multipart: the file and its type)

POST /v1/applications/current/documents

curl -X POST https://onboard.socialmatterspay.com/v1/applications/current/documents \
  -H 'Authorization: Bearer applicant_session_token' \
  -F 'doc_type=other' \
  -F 'file=@operating-agreement.pdf'

Response · 201

HTTP 201

{
  "data": {
    "document": {
      "id": "ee01c4c7-1800-45e6-9863-f8ceb45e6540",
      "doc_type": "other",
      "owner_id": null,
      "filename": "operating-agreement.pdf",
      "size_bytes": 31,
      "sha256": "fb37a48c7ba917ca20d4f959d6550db69ec3b25aa356bd03cb26ac466fdbfbaa",
      "statement_month": null
    },
    "application": "(the application, as GET /v1/applications/current answers it)"
  }
}

DELETE /v1/applications/current/documents/{documentId}

Remove a document from the draft (it stays on record as removed)

Applicant session

Host https://onboard.socialmatterspay.com

Parameters

Field	Notes
`documentId` requiredpath · string	—

Responses

Status	Meaning
`200`	Application
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

The same fields as under uploadApplicationDocument · application.

Example

Take a document off again

DELETE /v1/applications/current/documents/ee01c4c7-1800-45e6-9863-f8ceb45e6540

curl -X DELETE https://onboard.socialmatterspay.com/v1/applications/current/documents/ee01c4c7-1800-45e6-9863-f8ceb45e6540 \
  -H 'Authorization: Bearer applicant_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "object": "application",
    "id": "8f67c6ec-bbf9-4630-bbc3-9c95203955fe",
    "reference": "SMP-B94V-95JT",
    "status": "draft",
    "started_by": "applicant",
    "info_request_message": null,
    "contact": {
      "name": "Jennifer Thompson",
      "email": "jen31@sunrise31.example",
      "phone": "+13055550123",
      "email_verified": true
    },
    "business": {
      "legal_name": "Sunrise Wellness LLC",
      "dba_name": "Sunrise",
      "entity_type": "llc",
      "formation_state": "FL",
      "formation_date": "2019-04-02",
      "ein_last4": "0031",
      "address": {
        "line1": "1 Main St",
        "line2": "Suite 200",
        "city": "Tampa",
        "state": "FL",
        "postal_code": "33602"
      },
      "business_phone": null,
      "website_url": "https://sunrise31.example",
      "name_differs": true,
      "terms_page_url": null,
      "name_link_proof": "dba_certificate"
    },
    "sales": {
      "products_description": "Yoga mats and studio gear",
      "category": "retail",
      "monthly_volume_cents": 2500000,
      "avg_ticket_cents": 8500,
      "max_ticket_cents": 60000,
      "refund_policy": "30 days, unused items",
      "current_processors": [
        "Stripe"
      ],
      "integration_types": [
        "woocommerce",
        "shopify"
      ],
      "is_startup": false,
      "statement_descriptor": "SUNRISE"
    },
    "owners": [
      {
        "id": "937483ec-19aa-4b69-9293-fb067752edf8",
        "full_name": "Jennifer Thompson",
        "title": "Managing Member",
        "ownership_pct": 60,
        "is_control_person": true,
        "is_applicant": true,
        "dob": "1980-01-01",
        "email": "jen31@sunrise31.example",
        "phone": null,
        "address": {
          "line1": "9 Bay Rd",
          "line2": null,
          "city": "Tampa",
          "state": "FL",
          "postal_code": "33606"
        },
        "ssn_last4": "1031",
        "id_status": "verified",
        "biometric_consent": true,
        "consent": {
          "can_answer": true,
          "by": "applicant",
          "at": "2026-10-28T00:23:30.542Z",
          "version": "biometric-notice-0.1-draft-2026-10-25",
          "sentence": "I have read SMP's Biometric Notice. I consent to Social Matter Payments LLC and its identity-verification provider collecting, storing and using a scan of my face geometry from my selfie and my ID photo, only to verify my identity for this application, and to its destruction on the schedule in that notice. I sign this release electronically as Jennifer Thompson.",
          "sentence_sha256": "cc28518cd8c709a6187e7c7038497f9931898501b3d049737ed65637575e9666",
          "locked": true
        },
        "invite_sent_at": null,
        "documents": {
          "id_front": {
            "id": "1dfa6649-42ba-417d-884c-3e38f7606169",
            "filename": "id_front.png",
            "content_type": "image/png",
            "size_bytes": 2048,
            "source": "camera",
            "uploaded_at": "2026-10-28T00:23:30.548Z"
          },
          "id_back": {
            "id": "51f8f430-b2a2-42b9-b98f-f3d53a5f9e89",
            "filename": "id_back.png",
            "content_type": "image/png",
            "size_bytes": 2048,
            "source": "camera",
            "uploaded_at": "2026-10-28T00:23:30.556Z"
          },
          "selfie": {
            "id": "d9941f1e-7bc9-4355-990b-2ceb54a11a77",
            "filename": "selfie.png",
            "content_type": "image/png",
            "size_bytes": 2048,
            "source": "camera",
            "uploaded_at": "2026-10-28T00:23:30.562Z"
          }
        },
        "verification": {
          "provider": "sandbox",
          "status": "verified",
          "provider_status": null,
          "sandbox": true,
          "checks": {
            "sandbox": true,
            "checks": [
              {
                "name": "image_format",
                "result": "pass",
                "detail": "ID front: png; ID back: png; selfie: png"
              },
              {
                "name": "resolution",
                "result": "pass",
                "detail": "ID front 1600×1200; ID back 1600×1200; selfie 1600×1200"
              },
              … 4 more
            ]
          },
          "created_at": "2026-10-28T00:23:30.568Z",
          "completed_at": "2026-10-28T00:23:30.568Z",
          "attempt": 1,
          "retry_available": false,
          "attempts_left": null,
          "reason": null,
          "fell_back": false
        }
      },
      {
        "id": "7ef70922-1eea-4cef-8b4f-b732c2ffe370",
        "full_name": "Marcus Lee",
        "title": "Member, operations",
        "ownership_pct": 40,
        "is_control_person": false,
        "is_applicant": false,
        "dob": "1982-03-04",
        "email": "marcus31@sunrise31.example",
        "phone": null,
        "address": {
          "line1": "9 Bay Rd",
          "line2": null,
          "city": "Tampa",
          "state": "FL",
          "postal_code": "33606"
        },
        "ssn_last4": "2031",
        "id_status": "verified",
        "biometric_consent": true,
        "consent": {
          "can_answer": false,
          "by": "owner",
          "at": "2026-10-28T00:23:30.586Z",
          "version": "biometric-notice-0.1-draft-2026-10-25",
          "sentence": "I have read SMP's Biometric Notice. I consent to Social Matter Payments LLC and its identity-verification provider collecting, storing and using a scan of my face geometry from my selfie and my ID photo, only to verify my identity for this application, and to its destruction on the schedule in that notice. I sign this release electronically as Marcus Lee.",
          "sentence_sha256": "d5830b920749ec3575bbb142dc76619e8057bfc9555432029d754a9bc4d4e6e1",
          "locked": true
        },
        "invite_sent_at": "2026-10-28T00:23:30.573Z",
        "documents": {
          "id_front": {
            "id": "0ce2b563-24dc-49ba-884a-2bf36c7a39cb",
            "filename": "id_front.png",
            "content_type": "image/png",
            "size_bytes": 2048,
            "source": "camera",
            "uploaded_at": "2026-10-28T00:23:30.593Z"
          },
          "id_back": {
            "id": "8112032a-d7c7-4af3-bc3c-1fc3787c55ba",
            "filename": "id_back.png",
            "content_type": "image/png",
            "size_bytes": 2048,
            "source": "camera",
            "uploaded_at": "2026-10-28T00:23:30.600Z"
          },
          "selfie": {
            "id": "7b1a22c2-5400-4115-ab66-0c7436814371",
            "filename": "selfie.png",
            "content_type": "image/png",
            "size_bytes": 2048,
            "source": "camera",
            "uploaded_at": "2026-10-28T00:23:30.605Z"
          }
        },
        "verification": {
          "provider": "sandbox",
          "status": "verified",
          "provider_status": null,
          "sandbox": true,
          "checks": {
            "sandbox": true,
            "checks": [
              {
                "name": "image_format",
                "result": "pass",
                "detail": "ID front: png; ID back: png; selfie: png"
              },
              {
                "name": "resolution",
                "result": "pass",
                "detail": "ID front 1600×1200; ID back 1600×1200; selfie 1600×1200"
              },
              … 4 more
            ]
          },
          "created_at": "2026-10-28T00:23:30.610Z",
          "completed_at": "2026-10-28T00:23:30.610Z",
          "attempt": 1,
          "retry_available": false,
          "attempts_left": null,
          "reason": null,
          "fell_back": false
        }
      }
    ],
    "ownership_attested": true,
    "documents": [
      {
        "id": "632da260-a3b9-4f3c-a97e-a214a6b66845",
        "doc_type": "ein_letter",
        "statement_month": null,
        "filename": "ein_letter.pdf",
        "content_type": "application/pdf",
        "size_bytes": 33,
        "uploaded_at": "2026-10-28T00:23:30.509Z"
      },
      {
        "id": "b235a72b-a193-42e9-b28e-cc9353e9e46b",
        "doc_type": "articles",
        "statement_month": null,
        "filename": "articles.pdf",
        "content_type": "application/pdf",
        "size_bytes": 39,
        "uploaded_at": "2026-10-28T00:23:30.516Z"
      },
      … 4 more
    ],
    "statement_months": [
      "2026-07",
      "2026-08",
      "2026-09"
    ],
    "bank": {
      "method": "plaid_sandbox",
      "status": "verified",
      "institution_name": "Plaid Sandbox: First Platypus Bank (simulated)",
      "account_type": "checking",
      "account_last4": "9606",
      "routing_number": "011401533",
      "holder_name": "Sunrise Wellness LLC",
      "name_match": "match",
      "sandbox": true
    },
    "referral": {
      "status": "none",
      "source": null,
      "partner_name": null,
      "agent_name": null,
      "claim": null
    },
    "integration": {
      "kind": "website",
      "domain": "sunrise31.example",
      "app_name": null,
      "app_platform": null,
      "app_store_url": null,
      "app_bundle_id": null,
      "method": "api",
      "label": "sunrise31.example",
      "sandbox": {
        "account_id": "4cad9448-209c-48b5-9a1f-95c8585a2db7",
        "key_prefix": "sk_sandbox_2ca1",
        "issued_at": "2026-10-28T00:23:30.468Z"
      },
      "status": "building",
      "page_url": null,
      "applicant_notes": null,
      "submitted_at": null,
      "due_at": null,
      "place": null,
      "decision": null,
      "cases": [
        {
          "id": "bank_linked",
          "title": "Link a bank",
          "how": "Link a payer’s bank with the sandbox bank link (any test bank)."
        },
        {
          "id": "payment_settled",
          "title": "A payment that settles",
          "how": "Make a WEB payment that carries the authorization words’ SHA-256, then move the sandbox clock until it settles."
        },
        … 7 more
      ],
      "page_checks": [
        {
          "id": "payer_name",
          "title": "The payer",
          "looks_at": "asks for the payer’s real name; no placeholder"
        },
        {
          "id": "authorization",
          "title": "The authorization",
          "looks_at": "SMP’s authorization words in full before the button, and a tick box that unlocks the button"
        },
        … 4 more
      ]
    },
    "pricing": null,
    "agreements": [
      {
        "key": "merchant-agreement",
        "title": "Merchant Agreement",
        "box": "agreements",
        "version": "0.1",
        "draft": true
      },
      {
        "key": "merchant-schedules",
        "title": "Merchant Agreement — Schedules A to E",
        "box": "agreements",
        "version": "0.1",
        "draft": true
      },
      … 8 more
    ],
    "signatures": [],
    "signed_documents": [],
    "submitted_at": null,
    "review": null,
    "problems": [],
    "config": "(the questionnaire's settings, as GET /v1/applications/config answers them)"
  }
}

POST /v1/applications/current/bank/link-token

Start the bank step: a Plaid Link token (Auth + Identity), or which fallback applies

Applicant session

Host https://onboard.socialmatterspay.com

Responses

Status	Meaning
`200`	mode: plaid (with link_token), sandbox, or document_only
`401`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`mode`enum	plaid when a Plaid Link token is returned; sandbox or document_only when the bank is proved another way (document_only also when Plaid could not be reached). one of `plaid`, `sandbox`, `document_only`
`link_token`string	Plaid Link token, only when mode is plaid.
`expiration`string	When the Link token expires, as Plaid reports it. Only when mode is plaid.
`message`string	Only when Plaid could not be reached: tells the applicant to upload a voided check, a bank letter or a bank document instead.

Example

status 200 in this build: Plaid keys are not configured.

Start a Plaid bank sign-in for the payout account

POST /v1/applications/current/bank/link-token

curl -X POST https://onboard.socialmatterspay.com/v1/applications/current/bank/link-token \
  -H 'Authorization: Bearer applicant_session_token'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "mode": "sandbox"
  }
}

POST /v1/applications/current/bank/plaid

Finish Plaid Link: the account and routing numbers (sealed) and the names on the account, compared with the business and its owners

Applicant session

Host https://onboard.socialmatterspay.com

A match on the business’s name verifies the account; a near match or an owner’s name goes to a person; anything else asks for another proof.

Request body

Field	Notes
`public_token` requiredstring	—
`account_id` requiredstring	—

Responses

Status	Meaning
`200`	status: verified, manual_review or name_mismatch; and the application
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`409`	Error — error shape and codes
`503`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`status`enum	verified when the account holder matches the business; name_mismatch when the names on the account match none of the business or its owners; manual_review otherwise. one of `verified`, `name_mismatch`, `manual_review`
`application`object	The application as its applicant sees it. An owner who opened their own emailed link gets a limited view, with only owner_scope, legal_name, that owner and the config; the other fields are for the applicant. Its fields are listed under `uploadApplicationDocument · application`.

Example

status 409 in this build: Plaid keys are not configured.

Connect the payout bank with Plaid's public token

POST /v1/applications/current/bank/plaid

curl -X POST https://onboard.socialmatterspay.com/v1/applications/current/bank/plaid \
  -H 'Authorization: Bearer applicant_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "public_token": "public-sandbox-00000000-0000-0000-0000-000000000000",
  "account_id": "plaid-account-id"
}'

Response · 409

HTTP 409
Cache-Control: no-store

{
  "error": "plaid_not_configured",
  "message": "Plaid isn’t set up here. Upload a document instead."
}

POST /v1/applications/current/bank/sandbox

Sandbox only: Plaid’s documented test checking account; the account holder’s name is simulated (the legal name unless given) and the name check runs for real

Applicant session

Host https://onboard.socialmatterspay.com

Request body

Field	Notes
`account_owner_name`string	—

Responses

Status	Meaning
`200`	status and the application
`401`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`status`enum	verified when the simulated account holder matches the business; name_mismatch when it matches none of the business or its owners; manual_review otherwise. one of `verified`, `name_mismatch`, `manual_review`
`application`object	The application as its applicant sees it. An owner who opened their own emailed link gets a limited view, with only owner_scope, legal_name, that owner and the config; the other fields are for the applicant. Its fields are listed under `uploadApplicationDocument · application`.

Example

Connect the payout bank (a sandbox test bank)

POST /v1/applications/current/bank/sandbox

curl -X POST https://onboard.socialmatterspay.com/v1/applications/current/bank/sandbox \
  -H 'Authorization: Bearer applicant_session_token' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "status": "verified",
    "application": "(the application, as GET /v1/applications/current answers it)"
  }
}

POST /v1/applications/current/bank/manual

The fallback: the numbers as typed, and a voided check, bank letter or bank document a person compares them with

Applicant session

Host https://onboard.socialmatterspay.com

Request body

Field	Notes
`routing_number` requiredstring	—
`account_number` requiredstring	—
`account_type` requiredenum	one of `checking`, `savings`
`proof_document_id` requiredstring	—

Responses

Status	Meaning
`200`	status: manual_review; and the application
`400`	Error — error shape and codes
`401`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

Field	Notes
`status`string = "manual_review"	Always manual_review: a person compares the typed numbers with the proof document.
`application`object	The application as its applicant sees it. An owner who opened their own emailed link gets a limited view, with only owner_scope, legal_name, that owner and the config; the other fields are for the applicant. Its fields are listed under `uploadApplicationDocument · application`.

Example

Or type the numbers, with a voided check a person compares them with

POST /v1/applications/current/bank/manual

curl -X POST https://onboard.socialmatterspay.com/v1/applications/current/bank/manual \
  -H 'Authorization: Bearer applicant_session_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "routing_number": "110000000",
  "account_number": "000555666777",
  "account_type": "checking",
  "proof_document_id": "6432ecc3-8964-4754-b4e9-b01762b60229"
}'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "status": "manual_review",
    "application": "(the application, as GET /v1/applications/current answers it)"
  }
}

Upload a document, sealed byte for byte before storage (10 MB). ID photos and selfies are photos only, never a PDF.

Request body (multipart/form-data)

Responses

Fields of data (201)

Remove a document from the draft (it stays on record as removed)

Parameters

Responses

Fields of data (200)

Start the bank step: a Plaid Link token (Auth + Identity), or which fallback applies

Responses

Fields of data (200)

Finish Plaid Link: the account and routing numbers (sealed) and the names on the account, compared with the business and its owners

Request body

Responses

Fields of data (200)

Sandbox only: Plaid’s documented test checking account; the account holder’s name is simulated (the legal name unless given) and the name check runs for real

Request body

Responses

Fields of data (200)

The fallback: the numbers as typed, and a voided check, bank letter or bank document a person compares them with

Request body

Responses

Fields of data (200)

Fields of `data` (201)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)

Fields of `data` (200)